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:
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:
As might be obvious, this is from a cm document that describes the markup language for content based markup.
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 topic, theme, example, code, api, see, definition, amongst others.
- A 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.