Inserting an informalfigure in DocBook

[dcramer]

Hi there,
As far as I can tell, the Insert Graphic action doesn't allow you to insert an informalfigure and also doesn't allow you to insert a figure within a paragraph. There are times when you want to have a single paragraph with a figure in the middle: <para>Blah blah <figure>...</figure> more text.</para> For example, if you intend to xinclude that para in more than one place, you really want the figure in the para and not have to do <para>Blah blah</para> <figure>...</figure> <para>more text.</para>.

Is that correct? Or have I missed something obvious

Thanks,
David

[Radu]

Hi David,

So the current behavior of the Insert Graphic action in Docbook 5 is:

1) In inline contexts (inside paragraphs for example) inserts an:

Code: Select all

<inlinemediaobject>

                <imageobject>

                    <imagedata fileref="file:/C:/path/image.gif"/>

                </imageobject>

</inlinemediaobject>

2) In block context (between paragraphs) insets:

Code: Select all

<figure>

            <title>image.gif</title>

            <mediaobject>

                <imageobject>

                    <imagedata fileref="file:/C:/path/image.gif"/>

                </imageobject>

            </mediaobject>

</figure>

The action is implemented in a Java Author operation called:
ro.sync.ecss.extensions.docbook.InsertImageDataOperation
You can find the Java sources for it in the Author SDK:
http://www.oxygenxml.com/developer.html ... horing_SDK

So you could implement your own custom operation for inserting graphics in a given context, pack it in a jar library and add it to the Docbook 5 document type's Classpath.

If you have improvement suggestions for our own "Insert Graphic" action please let us know.

Regards,
Radu

[dcramer]

Hi Radu,
Ok, that's what I thought. Yes, I think this is a case where "Insert Graphic" should be improved since this would apply to anyone using DocBook and isn't something idiosyncratic in our use of DocBook.

I can think of two ways to do this. The first is more generic and would free you from the need to create schema-specific classes for inserting images:

First, the framework-maintainer creates actions that insert constructs like this:

Code: Select all

    <figure xml:id="{$ro.sync.ecss.GenerateIdOperation}">

        <title>Sample Text</title>

        <mediaobject>

            <imageobject>

                <imagedata fileref="{$ro.sync.ecss.GenericFilePickerOperation('Choose image','.png,.gif,.jpg,.svg')}"/>

            </imageobject>

        </mediaobject>

    </figure> 

You would create additional actions for <informalfigure>, <inlinegraphic>, and any other constructs that matter to you.

When this operation is invoked, Oxygen inserts the XML and replaces {$ro.sync.ecss.GenerateIdOperation} with a generated ID and {$ro.sync.ecss.GenericFilePickerOperation} causes a file picker to be invoked with a title of 'Choose image' and which shows only the files of the types listed in the second parameter.

Then in the GUI, the framework-maintainer adds an Insert Graphic drop-down button with choices for inserting a figure, informalfigure, or inlinegraphic.

The second way would be simply to modify ro.sync.ecss.extensions.docbook.InsertImageDataOperation so that in addition to the URL field, there's an Element field with a drop-down that lets you pick figure, informalfigure, or inlinegraphic. That solves the problem for now, but it's a matter of time before someone wants a special action for inserting flash files or mp3 files or something else.

The generic way is better. I'm not sure if you already have a way in Oxygen to put replaceable markers in the inserted XML like that, but perhaps you see what I'm getting at in general and can think of the right way to implement it.

Thanks,
David

[Radu]

Hi David,

Thanks for the interesting ideas. They will be discussed.
We've had the idea of adding support for code templates in the small XML fragment which gets inserted by the Author actions for some time and maybe in a future Oxygen version it will get implemented.

Regards,
Radu

[dcramer]

I ended up creating four classes based on InsertImageDataOperation: InsertFigureOperation, InsertInformalfigureOperation, InsertScreenshotOperatoin and InsertInlinemediaobjectOperation. I then created one action for each of these named figure, informalfigure, screenshot, and inlinemediaobject. I created an actions group on the toolbar containing each of these and created a submenu with the three operations as well. I then added each of these operations to the "Content Completion (Author Custom Actions)" list and removed the corresponding elements.

In this case, I think it's better to let the user decide what element to enter instead of having Oxygen deciding for him. The DocBook schema allows <figure>s, <informalfigure>s, and <screenshot>s in <para>s, so making all graphics inside paras into <inlinemediaobject>s is incorrect.

David

[cbr]

for dcramer...

I'd be very interested in these classes. One of the first things I tried was inserting a screenshot (not just the generic "graphic"), and found myself looking up docbook reference and fiddling with property editors, instead of click-and-browse-for-image. I had to create the XML and copy the filename as an attribute value.

I'd also be very interested in that as standard, if anyone's listening...

[dcramer]

Doesn't look like I can attach a zip to this forum, so here's the code for the informalfigure one (just a tweak of the existing Oxygen one). The figure and inlinemediaobject ones are almost identical with only the element names changed. I've also written a similar one for inserting xincludes, so you get a file chooser that lets you pick an xml file:

Code: Select all

package org.docbook.oxygen;



import ro.sync.ecss.extensions.api.ArgumentDescriptor;

import ro.sync.ecss.extensions.api.ArgumentsMap;

import ro.sync.ecss.extensions.api.AuthorAccess;

import ro.sync.ecss.extensions.api.AuthorOperation;

import ro.sync.ecss.extensions.api.AuthorOperationException;

import ro.sync.ecss.extensions.api.schemaaware.SchemaAwareHandlerResult;

import ro.sync.ecss.extensions.commons.ImageFileChooser;



public class InsertInformalfigureOperation implements AuthorOperation {



	/**

	 * @see ro.sync.ecss.extensions.api.AuthorOperation#doOperation(ro.sync.ecss.extensions.api.AuthorAccess, ro.sync.ecss.extensions.api.ArgumentsMap)

	 */

	public void doOperation(AuthorAccess authorAccess, ArgumentsMap args)

	throws IllegalArgumentException, AuthorOperationException {

		String ref = ImageFileChooser.chooseImageFile(authorAccess);

		if(ref != null) {

			insertImageRef(authorAccess, ref);

		}

	}



	/**

	 * @param authorAccess Author access

	 * @param ref The image reference

	 * @return The insertion result

	 * @throws AuthorOperationException

	 */

	public static SchemaAwareHandlerResult insertImageRef(AuthorAccess authorAccess, String ref) throws AuthorOperationException {

		SchemaAwareHandlerResult result = null;

		StringBuffer fragment = null;

		fragment = new StringBuffer();

		fragment.append("<informalfigure xmlns=\"http://docbook.org/ns/docbook\">");

		fragment.append("<mediaobject><imageobject><imagedata fileref=\"");

		fragment.append(ref);

		fragment.append("\"/></imageobject></mediaobject></informalfigure>");



		// Insert the graphic

		result = authorAccess.getDocumentController().insertXMLFragmentSchemaAware(

				fragment.toString(),

				authorAccess.getEditorAccess().getCaretOffset());

		return result;

	}



	/**

	 * No arguments. The operation will display a dialog for choosing the image fileref.

	 * 

	 * @see ro.sync.ecss.extensions.api.AuthorOperation#getArguments()

	 */

	public ArgumentDescriptor[] getArguments() {

		return null;

	}



	/**

	 * @see ro.sync.ecss.extensions.api.Extension#getDescription()

	 */

	public String getDescription() {

		return "Insert a DocBook informalfigure";

	}

}

[dcramer]

cbr,
Since you're interested in the DocBook framework, I made a little movie of some other customizations that I did and think should be candidates for the docbook framework:

http://www.thingbag.net/docbook/oxygen.ogv

I made dropdown buttons out of Bold, Italic, and added one for Monospace, and made the list buttons dropdowns and added one for admonitions etc.

David