Bug 696870

Summary: Support for topics that contain images.
Product: [Other] Topic Tool Reporter: Stephen Gordon <sgordon>
Component: cli-Topic_ToolAssignee: Stephen Gordon <sgordon>
Status: CLOSED CURRENTRELEASE QA Contact:
Severity: high Docs Contact:
Priority: unspecified    
Version: 0.0.xCC: topic-tool-list
Target Milestone: ---   
Target Release: ---   
Hardware: x86_64   
OS: Linux   
Whiteboard:
Fixed In Version: topic-tool-0.0.5-1 Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of: Environment:
Last Closed: 2011-09-29 04:22:26 UTC Type: ---
Regression: --- Mount Type: ---
Documentation: --- CRM:
Verified Versions: Category: ---
oVirt Team: --- RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: --- Target Upstream Version:

Description Stephen Gordon 2011-04-15 04:49:27 UTC 
Description of problem:

The Topic Tool does not currently support the use of images within topic fragments except where these images already exist in all books that use the topic. This has been discussed at length, see:

   https://engineering.redhat.com/rt3/Ticket/Display.html?id=102822

To implement an initial solution to this we would like to:

* Modify topic import to parse any imagedata references in the topic, if any are found:
   * Create a <topicname>.images/ directory in the topic path specified.
   * Import the image in it.
   * Update the imagedata fileref value to use a path relative to TopicRepository.
   * Also need to keep track such that if one image is used multiple times it doesn't get re-uploaded over and over.
* Modify topic export to:
   * Pull down images from imagedata references to <book>/en-US/topics/images/, creating topic path below that level as necessary.
   * Update the imagedata fileref value.
* Modify topic list/tree functions and any topic path validation routines such that directories ending in .images are not available for checking in topics.
* Modify topic commit to commit both the specified XML file and any images. Will also need to copy images to preview directory for Test_Book.

Further issues may arise during development but implementation of the above will give us something to poke holes in.
Comment 1 Stephen Gordon 2011-04-16 15:15:33 UTC 
To add to the description the addition of support for images will also break the current implementation of `topic clone`. Some minor action to be taken initially to ensure that `topic clone` does not allow cloning of topics containing images. Support for this will need to be added later.
Comment 2 Stephen Gordon 2011-04-17 15:01:17 UTC 
Changes have been checked into trunk which move to facilitate this however some issues have been encountered. The original plan was to place exported images in the topics/ sub-directory, in a mirror of the topic tree.

As it turns out when I have exported  a book that drags down (into the en-US directory) 'topics/Reference/My_Test_Topic_2.xml' and the operation also brings down included image 'topics/References/My_Test_Topic_2.images/llama.png' publican throws a warning building the book. The error thrown is:

   WARNING: Image missing: tmp/en-US/xml/test/llama.png

The reason appears to be that publican only copies images from 'images/' across to the area it uses for building. Changing the export to put images into, for example 'images/References/My_Test_Topic_2.images/llama.png' and having the xml point at this the warning was no longer thrown.

Instead however at the next step fop (when building pdfs) throws:

   SEVERE: Image not found: My_New_Topic_2.images/llama.png

This is not surprising as you may recall from above that the path is actually 'images/References/My_Test_Topic_2.images/llama.png'. Building in html or html-single doesn't throw an error but when viewing the resultant html no image is show because again it appears to be looking for 'My_Test_Topic_2.images/llama.png'. This is made more odd by the fact that the html build has actually successfully replicated the full path and put the image in it. Based on this it seems that the toolchain, intentionally or otherwise, forces the 'images/' directory to be flat with no sub-directories.

The most likely workaround for this for now will be to escape the path and export 'images/References_My_Test_Topic_2.images_llama.png'.
Comment 3 Stephen Gordon 2011-04-18 05:59:33 UTC 
(In reply to comment #2)

The second of these issues was a furphy. The way I have initially implemented this is as follows:

To create a topic with images:
1) Use `topic create <Template> <MyTopicName>` to create the topic.
2) To include images make a directory called '<MyTopicName>.images' in the same directory, place any images you wish to use in the topic within the folder.
3) In the topic xml set the fileref to refer to a relative location of the form '<MyTopicName>.images/<MyImageFileName>'. Do not use an absolute path.
4) Use `topic import <MyTopicName> <TopicPath>` as normal to import the topic and associated images.

On export:
1) Topics are downloaded into the exported copy of the book in 'en-US/topics/...' with the topic path used to create directories mirroring those in which the topic is stored in the repository.
2) Images are downloaded into 'en-US/images/...' with the topic path again used to create sub-directories mirroring those in which the topic is stored in the repository.

This change has also resulted in:
- Topic list functions being updated to filter out the image directories.
- Topic clone being updated to detect input topics which contain images. Cloning of topics with images is currently not supported.
- Topic export has largely been re-written to facilitate the above. As a side effect the previous limit for 'topic in topic' functionality of 3 levels of files has been removed.
Comment 4 Stephen Gordon 2011-04-20 04:33:18 UTC 
Further updated such that referenced images do not need to be placed in '<MyTopicName>.images' directory. They will be copied there automatically.