code-examples

Code Examples

Per the microformats process this is an examples page documenting existing real world examples of source code published on the Web. Next steps are to research code-formats and then proceed with code-brainstorming.

The Problem

Source code is published around the web in nonstandard formats, this makes actual use more difficult as it a) obscures possible licensing issues, doesn't encapsulate the source code in standard machine readable formats, and doesn't keep important meta data such as authors, language types and language version, with the source code in a machine readable fashion.

Participants

• Anders Conbere

Real-World Examples

[Example #1 LXR]

Mozilla - LXR

• uses <pre> to designate code block
• composed of:
  • Programming language inline at the top
  • License is inline in comments in the code block
  • Author is inline with the license
  • the code block is further complicated by having line numbers

[Example #2 PHPClasses]

PHPClasses - Viewing a file

• uses table rows to encapsulate data regarding the file
• code is designated by <pre>
• composed of:
  • File Name
  • File Version
  • Author Name
  • Author Webpage
  • Author Email
  • License (inline)
  • Content type
  • Description
• license, author data, and programing languge version are located in the class data as well as inline with the file

[Example #3 Php.net]

Php.net ldap functions

• uses <div> to designate the code block
• Has an assumed free license, and no other metadata attached to the code
• code is a mess for syntax highlighting purposes

[Example #4 Bigbold snippets]

A Python decorator

• uses <pre> to designate the block of code
• source code is a mess to account for syntax highlighting
• composed of:
  • Author
  • Author webpage
  • Programming language

[Example #5 CodeHighlighter]

CodeHightlighter A syntax highlighter written in Javascript (can be used e.g. for code snippets in blogarticles). Examples for markup (for CSS, HTML, Ruby code)

• <pre><code class="ruby"># ruby code</code></pre>
• source code is plain text
• composed of:
  • programming language (designated through the class attribute)

Existing Practices

Common Patterns

• pre and code blocks are common wrappers around code blocks.
• Author, and various author details are commonly included.
• License's are less common, and if the exist most commonly exist inline with the source code.
• Often times the language and version are to be assumed either by the type of site or the tags associated with that post.

Existing Solutions

• CodeHightlighter: Javascript syntax highlighter that attempts to maintain the semantic html structure of the code block without muddling it with styling. Designates the programming language of the code through the class attribute.

Proposal

• Early drafts
• Link to related pages as they become available
  • -brainstorming
  • - proposal
  • -microformat

See Also

• Other microformats
• Normative references for tags used