code-examples

2007-01-29T21:19:31Z

Aconbere: /* The Problem */

= 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, b) doesn't encapsulate the source code in standard machine readable formats, and c) doesn't keep important meta data such as authors, language types and language version, with the source code in a machine readable fashion.

== Participants ==
* [http://anders.conbere.org/ Anders Conbere]

== Real-World Examples ==

=== LXR ===
[http://lxr.mozilla.org/mozilla1.8/source/browser/app/nsBrowserApp.cpp Mozilla - LXR]

* uses <code><pre></code> 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

=== PHPClasses ===
[http://www.phpclasses.org/browse/file/10684.html PHPClasses - Viewing a file]

* uses table rows to encapsulate data regarding the file
* code is designated by <code><pre></code>
* 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 [http://www.phpclasses.org/browse/package/2544.html class data] as well as inline with the file

=== Php.net ===
[http://us3.php.net/ldap Php.net ldap functions]

* uses <code><div></code> 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

=== Bigbold snippets ===
[http://www.bigbold.com/snippets/posts/show/3346 A Python decorator]

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

=== CodeHighlighter ===
[http://www.danwebb.net/2006/9/3/low-pro-unobtrusive-scripting-for-prototype CodeHightlighter] A syntax highlighter written in Javascript (can be used e.g. for code snippets in blogarticles). [http://svn.danwebb.net/external/CodeHighlighter/trunk/index.html Examples for markup (for CSS, HTML, Ruby code)]

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

=== ASPN ===
[http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/501154 Python Cookbook]

* uses <code><pre class="code"></code> to designate the block of code
* once again the source code is a mess to account for syntax highlighting
* composed of:
** Link to plain text version of source
** Title
** Submitter
** Last Updated
** Version no
** Category
** Description
* The language is again assumed from the location on the site

== Existing Practices ==
=== Common Patterns ===

* pre and code blocks are common wrappers around code blocks.
* Author, and various author details are commonly included.
* Descriptions, Titles, and the version of the supplied code are common elements
* 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 ===

* [http://www.danwebb.net/2006/9/3/low-pro-unobtrusive-scripting-for-prototype 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
** [[code-brainstorming]]
** - proposal
** -microformat

== See Also ==
* ''Other microformats''
* ''Normative references for tags used''

code-brainstorming

2007-01-29T19:38:14Z

Aconbere:

= Code Brainstorming =

This is a brainstorm for the code microformat. See also [[code-examples|examples of code]] in the wild.

== The Problem ==

There are numerous sites on the Internet that seek to:
*Teach a programming language
*Document a programming language
*Collect examples or bits of code for reuse in the general community
*Show off a particularly interesting section of code.

Examples are:
*[http://docs.python.org/tut/ tutorials]
*[http://php.net/ language documentation]
*[http://aspn.activestate.com/ASPN/ programming communities]
*[http://www.b-list.org/weblog/2006/11/16/django-tips-get-most-out-generic-views blogs].

Each of these sites encapsulates their source code in different fashions and wraps up the metadata in different ways, this makes the source code found around the web largely indigestible by machines.

So by consolidating common practices into a standard format, you a) allow web developers a standard representation of source code online, and b) offer it in a format that is digestible by computers. This more than anything allows for interesting use by users. It would for instance allow users to collect code examples from the web and store them on their local machines in meaningful ways, which in turn allows them to organize and search that new source code repository for examples, classes or snippets that relate to their problem, and further gives them the information necessary to safely use that source code (license, author, language, etc.)

== Elements that come up often in practice ==

=== Base Elements ===

* module_title
* author(s) (might be a list)
** this should probably be an hcard
** author's name
** author's webpage
** author's email
* license (might be a link or written out)
* description (one liner)
* source-code (should always be plain-text with no additional markup)
* module_version (of source code)
* module_date (last updated)
* program-language (perl, php, python, etc.)
** language-version (5.8, 4, 2.4)
* module_url (linking back to the source of the module)
* category(s)
** a list of rel-tags

== Additional Suggestions ==

== Issues ==

==See also==

*[[code-examples]]

2007-01-25T18:36:23Z

Aconbere: /* Existing Practices */

code-examples

2007-01-25T18:30:50Z

Aconbere: /* Real-World Examples */

code-examples

2007-01-25T18:30:34Z

Aconbere: /* Real-World Examples */

code-examples

2007-01-25T18:06:46Z

Aconbere: /* Real-World Examples */

code-examples

2007-01-25T18:06:26Z

Aconbere: /* Real-World Examples */

code-examples

2007-01-25T18:06:03Z

Aconbere: