Skip to main content

Concept Oriented Markup

I have long been frustrated with all the different text mark up languages and word processors that I have used. There are many reasons for this; but the biggest issue is that markups (including very powerful ones like TeX) are not targeted at the kind of stuff I write.

Nowadays, it seems archaic to still be thinking in terms of sections and chapters. The world is linked and that applies to the kind of technical writing that I do.

I believe that the issue is fundamental. A concept like "section" is inherently about the structure of a document. But, what I want to focus on are concepts like "example", "definition", and "function type".

A second problem is that, in a complex environment, the range of documentation that is available to an individual reader is actually composed of multiple sources. Javadoc exemplifies this: an individual library may be documented using Javadoc into a single HTML tree. However, most programmers require access to multiple libraries; each with its own Javadoc. What would be nice would be seamless access to all relevant documentation from a single portal.

Hence the introduction of a new kind of document markup language: concept oriented markup. This is (will be) structured around a series of technologies:

  • The fundamental unit of document is the concept.

  • There is an ontology of concept types; my current list includes topicthemeexamplecodeapiseedefinition, amongst others.

  • graph is a network of concepts that are related for any reason. A graph is typically assembled from a combination of markup processing and source text processing.

  • A textual markup language that allows hand-written concepts to be written

  • A series of rendering engines that process graphs into HTML/PDF/LateX etc.

  • Software tools that make editing graphs easier.


So far, I have designed a simple markup language together with the meta-architecture for representing concepts as a graph. I don't claim that this markup is 'pretty'; it is not simple enough yet.

Here is an example:
@topic
@id topic
@about{Topics}
A {@link topic} is a description of a topic of interest.
All topics have an {@link id}. If one is not given explicitly, then it will be
generated automatically.
@see{id}
@see{link}
@see{text}
@see{example}
@end topic

As might be obvious, this is from a cm document that describes the markup language for content based markup.

Popular posts from this blog

Existential Types are the flip side of generics

Generic types, as can now be seen in all the major programming languages have a flip side that has yet to be widely appreciated: existential types.

Variables whose types are generic may not be modified within a generic function (or class): they can be kept in variables, they can be passed to other functions (provided they too have been supplied to the generic function), but other than that they are opaque. Again, when a generic function (or class) is used, then the actual type binding for the generic must be provided – although that type may also be generic, in which case the enclosing entity must also be generic.

Existential types are often motivated by modules. A module can be seen to be equivalent to a record with its included functions: except that modules also typically encapsulate types too. Abstract data types are a closely related topic that also naturally connect to existential types (there is an old but still very relevant and readable article on the topic Abstract types have …

Hook, Line and Sinker

It is well documented that people’s #1 fear is speaking in public! Effective and efficient public speaking is a whole topic in its own right; but a few simple tips might help to both improve your effectiveness and help to reduce the anxiety.

You may be called on to talk about your work at very short notice; or you may have a week’s notice; and you may be required to give a formal slide show or just a brief verbal update. Many, if not most of the issues, are the same.
The Hook
Newspaper editors call the first paragraph of an article ‘the hook’. Its meant to hook you into reading the rest of the piece. On the other hand, the classical ‘say what you are going to say, say it, and say what you said’ approach gives people plenty of time to switch off.

The hook may be playful, it may be controversial, but it must communicate why the listener should pay attention.
The Line
Its a conversation! Even if no one says anything they are listening and thinking; and maybe replying to you in their head. So, …