AA wiki markup
From ActiveArchives
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)
