Inserting an informalfigure in DocBook

Having trouble installing <oXygen/>? Got a bug to report? Post it all here.
dcramer
Posts: 154
Joined: Sat Aug 28, 2010 1:23 am

Inserting an informalfigure in DocBook

Post by dcramer » Tue Jan 25, 2011 7:24 am

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
Posts: 6811
Joined: Fri Jul 09, 2004 5:18 pm

Re: Inserting an informalfigure in DocBook

Post by Radu » Tue Jan 25, 2011 11:03 am

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
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

dcramer
Posts: 154
Joined: Sat Aug 28, 2010 1:23 am

Re: Inserting an informalfigure in DocBook

Post by dcramer » Tue Jan 25, 2011 6:06 pm

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
Posts: 6811
Joined: Fri Jul 09, 2004 5:18 pm

Re: Inserting an informalfigure in DocBook

Post by Radu » Wed Jan 26, 2011 10:55 am

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
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

dcramer
Posts: 154
Joined: Sat Aug 28, 2010 1:23 am

Re: Inserting an informalfigure in DocBook

Post by dcramer » Mon Jan 31, 2011 3:51 am

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
Posts: 1
Joined: Fri Feb 11, 2011 7:21 pm

Re: Inserting an informalfigure in DocBook

Post by cbr » Fri Feb 11, 2011 7:28 pm

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
Posts: 154
Joined: Sat Aug 28, 2010 1:23 am

Re: Inserting an informalfigure in DocBook

Post by dcramer » Sat Feb 12, 2011 1:47 am

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
Posts: 154
Joined: Sat Aug 28, 2010 1:23 am

Re: Inserting an informalfigure in DocBook

Post by dcramer » Sat Feb 12, 2011 2:30 am

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

Post Reply