Marking up code samples

When documenting programming languages we commonly include code snippets within the documentation to illustrate how to go about doing something. In HTML this would usually include <PRE> or <CODE> tags to inform the browser that we want to see this snippet in a non-proportional font with the white space preserved.

However, modern programming tools go one better and now markup this text with colour to assist with readability. So, rather than just displaying a block of black text they display something like this:

Is there an existing / standard way to do this with DITA?

 

I guess the best would be to create a specialization with tags like <codeblock language="java"/> or <java/> (replace java by your prefered language) and then create a DITA-OT plugin that would apply color coding depending on the language and the output.

Thanks Claude. Creating a plugin Sounds technical :)

If I copy sample code to the clipboard, I can easily manipulate it from RTF into tagged XML and paste it into my DITA text.

Unfortunately, while I can recognise colour on the text, I don't know the cause of it. For example, there may be more than one cause of the text being blue and this information isn't available inside the RTF.

I suppose just tagging a block with a tag that just means "this is blue" or "this is green" gets you in trouble around here.

Derek,

The thing is that unlike HTML (or RTF) DITA is not really about formatting, its more about semantics.

In your case you would say that "this is a bloc of VB scrip" and directly put your code as is, without decorations.

The processing would then take this information to create appropriate formatting for your target output (e.g. CSS classes for HTML).

I recommend you read this article about specialization http://www.ibm.com/developerworks/library/x-dita5/

Hope this helps,

Claude

http://vedovini.net/