DocBook: Copy/Paste For Examples

DocBook duckAs Norm Walsh observed:

It’s been suggested that the ability to cut-and-paste should be a “hard requirement” for HTML rendering of numbered program listings.

Yes. If you ask me for help, and I show you how to do what you want to achieve, you’d like to put that demonstration on your clipboard, take it to your workspace, paste and adjust it to meet your needs. (In that respect the line-numbered OpenDJ LDAP SDK examples leave something to be desired.)

Solving the general case, especially without JavaScript, does not look so easy. DocBook lets you add inline markup and also callouts. Some code excerpts do benefit from callouts. For an example, see Bob Stayton’s example olink target database.

The <programlisting>s in ForgeRock core docs do not yet have callouts, and I’ve been particularly violent, stripping inline markup as part of the customization layer, in order to use SyntaxHighlighter (which also does line numbering independently of what gets on your clipboard). Currently some inline emphasis gets lost that way.

If only there were also a way to have the same listings elegantly reformatted for Kindle-width screens…

Advertisements

Leave a comment

Filed under Docs, Tools

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s