AA wiki markup

From ActiveArchives
Jump to: navigation, search

Contents

Background / Inspiration

AA Wiki Markup has its origins in a number of "best practices" in lightweight markup and particularly wiki structured text.

(Semantic) MediaWiki

MediaWiki is perhaps the best known & used wiki system, used in Wikipedia and many other wikis. Pioneer of the double-bracket link and pipe to set label.

[[ Page name ]]
[[ Page name | label ]]
[[ Namespace:Page name | label ]]

SemanticMediaWiki extension adds ability to set "relation" types with a double-colon (to differentiate from namespace).

[[Speaker::Michael Moss]]

Also interesting are MediaWiki's templates

{{Thankyou|signature=Me|reason=being who you are}}

SRT

Lightweight text format for subtitles of movies.

1
00:00:20,000 --> 00:00:24,400
Altocumulus clouds occur between six thousand

2 00:00:24,600 --> 00:00:27,800 and twenty thousand feet above ground level.


Cool:

  • Super readable,
  • Timecodes and arrows split the document into title
  • Flat (no hierarchy).
  • Product of online ripping community, later embraced by commercial products, and finally being considered by the W3C as WebSRT (though not yet formally accepted)

Uncool:

  • The leading title numbers are cumbersome.

PmWiki

PmWiki has several interesting features in its structured text markup.

  • WikiStyles for convenient inline/span styling, and flexible notion of scope.
%p bgcolor=#ffeeee% The WikiStyle specification at the beginning of this
line applies to the entire paragraph, even if there are %blue% other
WikiStyle specifications %% in the middle of the paragraph.
  • In-page "directives" to for instance, set the title
(:Title Basic PmWiki editing rules:)
  • Sophisticated MediaWiki+ style linking
[[wiki sandbox]]es. the es becomes part of the link to the page named "wiki sandbox"
[[(wiki) sandbox]]. the link to the page named "wiki sandbox" appears as just "sandbox". 
[[wiki sandbox|#]]. the link appears with whatever title is defined by the wiki sandbox page itself (via an in-page directive).

Textile

  • A Writerly approach
  • Ability to include HTML (passes through)
  • Simple to learn

Markdown

  • Large community, implementation in many languages
  • Extension system for python-markdown
  • Metadata extension, allowing in-page data to affect / control behaviours of markup (extensions)
  • Attribute markup {@ ... }

Python Function Decorators

The current syntax for function decorators as implemented in Python 2.4a2 is:

@dec2
@dec1
def func(arg1, arg2, ...):
    pass

This is equivalent to:

def func(arg1, arg2, ...):
    pass
func = dec2(dec1(func))

RDF

  • Long-term "Archive"-friendly orientation/discipline of the XML community (with a focus on compliance to standards & interoperability)
  • Decade of development of a set of robust libraries & toolsets (servers, triple stores).
  • Involvement of many institutional archival projects
  • SPARQL query language

RDFa

The RDF communities response to microformats (the adhoc emergent conventions of certain markup patterns to indicate certain types of commonly occuring information in a webpage).

  • Reintegrates "data" with context.
  • Return to hypertext + "writing with data".
  • Support in command line tools like Redland

Difficulties:

  • Open-endedness (like RDF itself), inconsistent / incomplete implementations
  • Some parsers (librdfa) still require XML-well formedness which is often not the case of pages in the wild.
  • Very little actual use.

Microdata

Part of the emerging HTML5 "suite". A more pragmatic, and practice based approach to embedded data in hypertext. (In a sense a compromise between microformats and rdfa).

More limited, and thus more straightforward in its implementations:

Example: Python code to extract microdata from a webpage.


Deep Links

Possibility to address "sub-resources", eg:

http://www.example.com/example.ogv#t=10,20
http://example.org/doc.pdf#page=10

AA Markup Concepts

AA Markup is based on markdown and is implemented as extensions to python-markdown.

Sections

As in MediaWiki, Headers of differing levels create a document that exists as a hierarchy of sections.

Level 1 Headers define "top-level" sections which are boxes that are (optionally) positionable.


Annotations, Semantic Links, and Metadata

Metadata is typically visible text on the page, marked up in such a way as to machine readable.

Metadata takes two forms: links and marked up data. They are translated to both rdfa / microdata. Microdata has a notion of "scope" -- ie it is tied to a particular section / inline span of text.

Semantic links

[[Speaker:: Michael Moss]]

becomes:

<a rel="aa:Speaker">Michael Moss</a>

Metadata:

%%Date:: 100%%

Timecodes

Timecodes are recognized mark the starts of Level 2 sections with start (& optionally end) properties.

turning:

 00:23:45 --> 00:24:56

into:

## {@typeof=aa:clip} %%start:: 00:23:45%% --> %%end: 00:24:56%%

Example Annotation:

00:33:12,27--> 00:33:38 Teaser
{@style=color: red; font-family: Serif;}Antonia Baehr on angry audience reactions:
“One time I had this glass and I thought it was water, but it was fine white wine,
but since I expected water, it tasted like piss. Maybe theatre is like this.
You may need to know a little bit what you will get [before you see it].

Suggestion:

# My annotation {: about="http://example.org/video.ogg" }
00:23:45 --> 00:24:56

Could turn into

 <section class="section1" about="http://example.org/video.ogg">
 <h1>My annotation</h1>
 <section class="section2" about="http://example.org/video.ogg#t=23.45,24.56">
 <h2>...</h2>
 </section>
 </section>
 

Embed

Old style:

{{ http://www.jabberwocky.com/carroll/walrus.html | permalink july 2011 | xpath /html/body/p[2] }}

New style:

[[ embed::http://www.jabberwocky.com/carroll/walrus.html || permalink july 2011 || xpath /html/body/p[2] ]]

Attributes, Classes and Inline Styles

Python markdown supports attribute setting via:

{@style=left:200px; top: 200px}{@class=foo}

This syntax is depreciated in the last beta of python markdown (2.1.0 beta). The new syntax is:

{: #id .class attribute="value" }

Metadata

From [in Python]:

Meta-data consists of a series of keywords and values defined at the beginning of a markdown document like this:

Title:   My Document
Summary: A brief description of my document.
Authors: Waylan Limberg
         John Doe
Date:    October 2, 2007
blank-value: 
base_url: http://example.com

This is the first paragraph of the document.

extra stylesheets

One can add extra stylesheets using the `css` metadata key

css: http://meyerweb.com/eric/tools/css/reset/reset.css
     /static/css/custom.css

This is the first paragraph of the document.

Deleting a page

To delete a page, just edit the page and type "delete", and save the page.

Associate an annotation to a resource

In the last revision of aa.core.git, one can associate an annotation box (delimited by level one header) to a specific resource by prefixing it with the url of the resourse

http://url.to/some/ressource.ogg
# Teaser

Antonia Baehr on angry audience reactions: “One time I had this glass and I thought it was water, but it was fine white wine, but since I expected water, it tasted like piss. Maybe theatre is like this. You may need to know a little bit what you will get [before you see it]. (00:33:12,27 – 00:33:38)

The python decorators are quite nice visually, so it could be:

@http://url.to/some/ressource.ogg
# Teaser

Antonia Baehr on angry audience reactions: “One time I had this glass and I thought it was water, but it was fine white wine, but since I expected water, it tasted like piss. Maybe theatre is like this. You may need to know a little bit what you will get [before you see it]. (00:33:12,27 – 00:33:38)

We could even think of associating other properties by this mean

@style color: red; font-family: Serif; 
@rel http:ldkjldskjdslkjdslkjdslds
# Teaser

Antonia Baehr on angry audience reactions: “One time I had this glass and I thought it was water, but it was fine white wine, but since I expected water, it tasted like piss. Maybe theatre is like this. You may need to know a little bit what you will get [before you see it]. (00:33:12,27 – 00:33:38)

Related

Personal tools
Namespaces

Variants
Actions
Navigation
Toolbox