Click here for Privacy Policy
Caption Maker - a google docs add-on
Caption Maker - general
This page is designed to help you understand how and for what to use the Caption Maker
add-on.
Don't want to read...
If you don't want to read this manual, you can check the videos listed here, should be enough to get the gist of it:
Otherwise, proceed to read the information below to find out everything you want to know about Caption MakerThe buttons, options and other elements displayed on the right side of the page are the same as those displayed in the sidebar in google docs when Caption Maker is activated. To use this manual and get information on what each button, option and other elements do, click on them on the right side and the information will be displayed in the middle of this page. Beside information shown for elements in this sidebar, below you'll find information on how to install, activate and start using Caption Maker in google docs. To get back to this page, simply click on the main title above, i.e. "Caption Maker - Help"
For detailed information on how and what Caption Maker does, click on the
Or proceed below to the installation info.
Caption Maker - installation
In order to install Caption Maker you'll need to visit this site: Caption Maker and there click on the + FREE button. e.g.
Once installed, Caption Maker will show up in your google docs menu as an option displayed under Add-Ons, e.g.
Caption Maker - Enabling
At this point, Caption Maker is installed but not enabled for use, i.e. when you open
the Add-ons / Caption Maker menu, you only see Help option.
Then you need to follow this procedure to enable the Caption Maker add-on in this
specific document.
First click on Add-ons / Manage add-ons menu options. e.g.
Which when clicked will activate the add-on and display a sidebar similar to the one shown on this page. e.g.
And "voila", you can start using the Caption Maker to add captions to your images, tables and drawings, etc.
Images and Drawing options
Images and Drawings
This is the "general" enable / disable of captioning of Images and Drawings. Note that even when disabled, Caption Maker will still process all elements, it'll just think that you simply want to remove any existing image & drawing captions from the document.
So, please remember: If this checkbox is disabled, any recognized old captions on images and/or drawings will be REMOVED!
Placement
Placement settings allow you to choose whether you want to place new captions above or below the captioned element. This setting doesn't in any way affect old captions or recognition of such.
Format
Old and New format for caption allows you to define "rules" for recognition of old captions and generation of new captions.
-
Old - this edit box contains either a regular expression or a Caption Makers
custom
format string. To let Caption Maker know you want to use a regex, start the format with
{reg} and then continue writing a regular expression without any additional
quotations or markups, just the regex content.
Alternatively, you can use the same format as is used for generation of new captions, i.e. a static string in which you can use {c} as a placeholder for "count" and {t} as a placeholder for "text". As there are unlimited number of combinations of how your old captions might be formatted, it's impossible to define a perfect recognition pattern for them, so always go through the document afterwards and check manually if all the old captions have been recognized and processed correctly. Fix any that weren't manually or re-adjust parameters and try again. The default regex used is:
{reg}^(Figure|Image)[.\-\s\:\0-9]*([^\n]*)$
which should work for most scenarios, but e.g. if your document has captions that start with e.g. "Picture n." you might want to extend this regex with something like:
{reg}^(Figure|Image|Picture)[.\-\s\:\0-9]*([^\n]*)$
(If you figure out a better regex that works for a wider range of situations, please let me know) - New - as the name suggests, this edit box allows you to define the format of
the
captions generated by Caption Maker. The captions consist of 3 parts:
- static label - e.g. "Figure" or "Image", etc.
- counter - put it in as {c}
- text - put it in as {t}
NOTE: Counter should always go before Text, i.e. {c} before {t} otherwise caption recognition of old captions when you run it again, will work poorly...
Numbering
When creating new captions, Caption Maker will automatically insert the number of current element in regards to other elements of the same type. i.e. it will put a number "2" in the caption for the second image in your document, even if there are 5 tables before it. Note, Drawings and Images are grouped and counted together. This setting is there to allow you to offset that counting for the specific group of Images and Drawings, i.e. if you set the value here to 3, then the first Image or Drawing in the document will get a: 3 in it's caption, the next one: 4, and so on. This is useful if your documentation is split into multiple documents and you want the numbering to continue from document to document.
Screenshot below shows the warning message shown when you disable processing one of the element types:
Table options
Tables
This is the "general" enable / disable of captioning of Tables. Note that even when disabled, Caption Maker will still process all elements, it'll just think that you simply want to remove any existing table captions from the document.
So, please remember: If this checkbox is disabled, any recognized old captions on tables will be REMOVED!
Placement
Placement settings allow you to choose whether you want to place new captions above or below the captioned element. This setting doesn't in any way affect old captions or recognition of such.
Format
Old and New format for caption allows you to define "rules" for recognition of old captions and generation of new captions.
-
Old - this edit box contains either a regular expression or a Caption Makers
custom
format string. To let Caption Maker know you want to use a regex, start the format with
{reg} and then continue writing a regular expression without any additional
quotations or markups, just the regex content.
Alternatively, you can use the same format as is used for generation of new captions, i.e. a static string in which you can use {c} as a placeholder for "count" and {t} as a placeholder for "text". As there are unlimited number of combinations of how your old captions might be formatted, it's impossible to define a perfect recognition pattern for them, so always go through the document afterwards and check manually if all the old captions have been recognized and processed correctly. Fix any that weren't manually or re-adjust parameters and try again. The default regex used is:
{reg}^Table[.\-\s\:\0-9]*([^\n]*)$
which should work for most scenarios. (If you figure out a better regex that works for a wider range of situations, please let me know) - New - as the name suggests, this edit box allows you to define the format of
the
captions generated by Caption Maker. The captions consist of 3 parts:
- static label - e.g. "Table"
- counter - put it in as {c}
- text - put it in as {t}
NOTE: Counter should always go before Text, i.e. {c} before {t} otherwise caption recognition of old captions when you run it again, will work poorly...
Numbering
When creating new captions, Caption Maker will automatically insert the number of current element in regards to other elements of the same type. i.e. it will put a number "2" in the caption for the second table in your document, even if there are 5 images before it. This setting is there to allow you to offset that counting for tables i.e. if you set the value here to 3, then the first Table in the document will get a: 3 in it's caption, the next one: 4, and so on. This is useful if your documentation is split into multiple documents and you want the numbering to continue from document to document.
Screenshot below shows the warning message shown when you disable processing one of the element types:
Visual formatting options
The settings in this section apply to the visual styling of newly generated captions for all captioned elements.
Predefined style
This dropbox offers a selection of predefined styles which are available for any text in google docs. The safest option to use is "Normal Text" as it won't interfere with headings. But if you need to, you can use other options like Heading 5 and 6, which e.g. could be useful if you want to see your captions in the Table of Contents.
Alignment and Weight
The checkboxes here allow you to turn on some basic text options, such as:
- Center - will Set caption alignment to center of the page.
- Bold - will Set caption weight to bold
- Italic - will Set caption text to Italic
Font properties
Final option in this section allows you to change the basic properties of the newly generated captions. i.e.
- Size - basically to increase or decrease the font size of characters in the caption
- Color - to change the font color of the caption text
Selection marking
The two buttons in this section apply to selected part of the document only and are useful if you have images, tables or drawings in your document which you don't want to caption, but you still want to create captions for other elements of such type. Note, to select elements you wish to apply this on simply select that section of the document as if you wanted to copy/paste it and then while it's selected click on the appropriate button. If it's just a single element you want to mark, you can simply click on it once and then click the appropriate button.
Set caption off
This button tells Caption Maker to process the selected part of document and to set a NON CAPTION flag on any element found in this selection (i.e. images, tables and drawings). Elements with this "NON CAPTION" flag will be skipped when generating new captions. If they already had some caption and it gets recognized as such, it will be removed.
Set caption on
This button tells Caption Maker to process the selected part of document and remove any "NON CAPTION" flags on any elements found in this selection. Elements without this flag will be counted for and captioned normally.
Listing generation
The buttons in this section process the whole document and either insert new tables to the cursor position or simply update existing tables which were inserted using these buttons earlier.
List of images
Clicking on this button will tell Caption Maker to process the whole document and find all image and drawing captions with bookmarks which were generated by Caption Maker. Once all captions are found, it will generate a 1 cell table and insert in it a list of all the captions with their links to the elements they caption. Thus creating a "Table of Images" (i.e. similar to Table of Contents)
List of tables
Clicking on this button will tell Caption Maker to process the whole document and find all table captions with bookmarks which were generated by Caption Maker. Once all captions are found, it will generate a 1 cell table and insert in it a list of all the captions with their links to the elements they caption. Thus creating a "Table of Tables" (i.e. similar to Table of Contents)
Update lists
If you've previously already inserted Lists of Images and/or Tables, you can use this button to refresh the lists after doing any changes to the Images, Drawings and/or Tables in this document. It will simply remove any such old lists and generate new ones.
Example List of Images
The following screenshot shows what the generated List of Images looks like in a document, with all the captions shown in the list, and each list item is an active link to the bookmark in the caption.
Process document
The last button in the sidebar is the main button. Clicking on it initiates the full processing of the document and its elements. The processing will be done in accordance to the settings done in Options section of the sidebar and when all is complete, the document will be updated with new captions for those elements that were set to be captioned. Once you process the document for the first time and thus ensure that captions throughout the document are homogeneous, you can use this button every time you add, remove or reorder images, drawings or tables to re-enumerate, remove or add an caption placeholders quickly and easily.
WARNING: this tool is far from perfect and processes text autonomously, which means that occasionally it might mess-up your document (e.g. see screenshot below). If that happens, use the google documents feature "version history", to restore the version that was not messed-up.Even when it doesn't mess up your document, you should still make manual inspections to the content to make sure nothing is missing or malformed, etc.
So, what happens when I click Captionize
The processing of the document is fairly simple, but to understand the process, you first need to understand
the structure of a google document. In its core, a google document is basically very similar to a web
page or HTML if you prefer. I.e. it's divided into smaller elements which are pieced together to
form a document. These elements are divided into several different types, e.g. you have your: body,
images, tables, rows, cells, bookmarks, drawings, paragraphs, headers, footers, headings, etc.
All These elements come with some rules that define the relationship between them.
I.e. all paragraph, table, image and similar elements reside within the body element.
Which means that the body element is a "parent" element to all elements that are within it. From
the perspective of body element, then all elements that reside in it are thus it's "child" elements.
Furthermore, some elements can also contain child elements, e.g. you can have a paragraph element which is
inside a table cell element. All elements that are on the same "level" i.e. have the same "parent" element,
are therefore referred to sibling elements. Knowing this, now when you look at the document, you can see the
basic
structure of a big "body" element, containing hundreds of child elements of all types and some of those
child elements have children themselves.
A very simple example of such a document could look like this:
-
BODY
- heading
- paragraph 1
- table 1
- table 1 row 1
- table 1 cell 1
- image 1
- table 1 cell 2
- table 1 cell 1
- table 1 row 2
- table 1 cell 1
- paragraph 2
- paragraph 3
- table 1 cell 2
- table 2
- table 2 row 1
- table 2 cell 1
- image 2
- table 2
- table 1 cell 1
- table 1 row 1
- image 3
- paragraph
- etc...
In this example, you can see that e.g. paragraph, or image can be "directly" in the body element or in some
cases it can be a child element of some other element. This kind of structure makes it really hard
( and really slow ) to process all elements in the document regardless of their position in relation to the
body element. So, Caption Maker only processes table, image and drawing elements that are
inserted directly into the body element and ignores any elements whose "parent" element isn't body.
The screenshot below shows a paragraphs, table and an image within a table.
Captioning appeared only for the upmost table (blue) while the inner table and the image within
the table were ignored...
TIP #1: Don't insert images, tables, drawings into other elements (e.g. in tables, headers, footers, etc.) if you want them to be recognized by Caption Maker and captioned accordingly. And, don't use "Inline" images and drawings because that is very similar to putting them into a table.
Beside the hierarchy of these elements, Each element has some common attributes and some attributes specific to the type of the element. E.g. "paragraph" type elements have a "font style", "font size" etc. which "image" elements would have no use for. Similarly, "image" elements have their own attributes that wouldn't mean anything for a paragraph element. Caption Maker utilizes some of these attributes to place flags on elements which mark those elements as "Caption OFF" or "Caption ON". This allows you to have full control over which elements are captioned and which are not. E.g. you might have an image on the front page of the document for which you don't want to see any caption, nor do you want it to be "counted" in the document. Unfortunately, google document elements don't have an attribute which would be called "CAPTION" and which you could set to ON or OFF. But, Caption Maker finds ways around that. So, when you select a segment of a document, and then click on the "Set caption off" document, the Caption Maker will go through that part of the document body, and for every captionable element (i.e. image, drawing or a table) it'll do the following:- Table - it will get the border color of the table and change it by very small value to make it an odd number so that you won't notice the color change
- Images & Drawing - it'll set the "alternative text" property to "NO CAPTION"
Note: the "alternative text" or "alt text" attribute for images and drawings is a property that is rarely
used today. It used to be important for web pages when internet was young and computers were either slow
to load web pages or didn't have any graphics at all, so people used textual browsers to view web pages.
These days
this property is commonly used to enable visually impaired people to browse the web (or read google
documents)
as web page / document
authors are supposed to put in some description of the images into alt text property, so that text to voice
systems can "read out" the image contents. This is how google describes alt text:
"Alt text is accessed by screen readers for people who might have trouble seeing your content"
So, be aware that Caption Maker therefore removes the possibility of using this
"alt text" for
its original purpose for now.
In future versions, the alt text will be filled with additional information
(e.g. with the caption contents ) to improve the "readability" of the document
for the visually impaired. For now, you can set the alt text to whatever you like, and the image/drawing
will be captioned by default. It's only if you click "Set caption OFF" or "Set caption ON" that the
alt text is set to "NO_CAPTION" or cleared.
UPDATE: from version v1.1 onwards, Caption Maker preserves the alt_text.
I.e. clicking on "Set caption on" or "Set caption off" will not remove any text from alt_text field but
instead it will prepend the text with "NO_CAPTION" if turning caption off, or remove the prefix "NO_CAPTION"
if turning caption on!
- even: Caption
- odd: No caption.
That brings us to second and third usage tip:
TIP #2: When editing Alt_text, if you see a "NO_CAPTION" mark, don't delete it, as that would mark the element as captionable. Instead, expand the text with your description. And, don't click "Set caption on" or "Set caption off" if you want to keep the "alt_text" on those images. If by any chance you have an image, for which you have written the alt_text already, and now you just want to disable caption on it, simply edit the alt text and put NO_CAPTION at the beginning of the alt_text. Similarly, to re-enable captioning of some image/drawing you can manually edit alt_text and remove the "NO_CAPTION" part, keeping the remainder of alt_text.
TIP #3: Don't change border colors on tables after marking them as Caption ON or OFF with the Set caption on / off buttons. If you do change the border color, then please mark them again as this "tag" on them might be lost with the color change.
Now that we've explained the structure of the document, and how specific elements in the document are marked for captioning, we can move on to the actual captioning process. This is what Captionize button does:
- go through the body of the document, element by element and inspect every: table, drawing and image
- for every element found check the paragraph above and below it and try to match it against the
appropriate "Old" format as defined in the Options for that element type.
- If the captioning of this element type is "enabled" in options and,
- If "old caption" is found:
- try to extract the caption "text" without the "label" (e.g. Figure, Image, Table) and without the number.
- insert the new caption as per the settings in options, with the text part of the old caption, but with a new number, format, label and all other parameters of the caption.
- if no "old caption" was found, then simply add a label and a number per settings in options
- If "old caption" is found:
- If the captioning of this element type is "disabled" then simply remove any old captions that were found and don't add new ones
- If the captioning of this element type is "enabled" in options and,
- insert a bookmark in the caption, which will later be used to create a list of Tables or a list of Images/Drawings.
- once whole document is processed, display a "statistic" showing how many elements of each type were captioned of how many total and show a list of any "lost" captions due to e.g. captioning of certain element type being disabled (see example below).
This brings us to our fourth tip:
TIP #4: Always inspect the document after clicking "Captionize" button and use the google documents versioning feature to restore documents to previous state if you note any issues. Better still, use the feature to save a "named version" before and after captioning to make sure you don't loose any data due to Caption Maker. Once you've successfully processed the document for the first time, use Caption Maker after every image, table or drawing change to quickly re-enumerate and unify the captions.
Below is an example of an image that was captioned with Caption Maker in a google document, and just left to the caption, you can see an indicator that the caption has been bookmarked:
At this point, your document should have captioned images, drawings and tables, and you may want to create a
so
called "List of Images" and/or "List of Tables" which will have links to the bookmarks for all captions for
that category. e.g.
As bookmarks are recreated every time you click "Captionize" document, we come to the final tip:
TIP #5: After Captionizing the document, click on "Update Lists" to make sure all the List of Images and List of Tables are up to date and don't try to change the format of the Lists, as it'll just reset to default when you click Update Lists (customized List of Images and List of Tables are not yet supported!)
Hopefully, the information in this document will help you use Caption Maker successfully and efficiently.