Docs365 add-on

A Google Docs™ add-on

Basic concepts

The main Docs365 folder

When you use the add-on, a folder named Docs365 is added to your Google Drive. This folder will contain all your Docs365-maintained content. This folder contains folders for each project you create and three other very important folders:

  • The Output folder - when you compile a project, the output is by default placed here.
  • The Public Output folder - a folder that Docs365 makes public (anybody can view the contents in it). When you generate output, e.g. PDFs, they are by default added to this folder so that you immeaditly can share them with people by for example sending out links.
  • The Generic folder, which contains support files that are used when you work with topics that are not part of a project. There are several different kinds of support files,
TOCs, Stylesheets, Masterpages, Filtervalue-sets, Variable-sets and Targets.

Stylesheets (and true custom styles)

Shared stylesheets are powerful tools to keep all the documents in sync. Stylesheets can be used in three ways. It allows you to quickly make all your documents look the same, just open a document and apply the stylesheet in question. Secondly it enables you to use true custom styles in Google Docs, e.g. you can add new custom styles such as "Address" and "CompanyLogo". And thirdly you can use it to fine tune how your docs are converted to other formats such as HTML and PDF.

Variables

Docs365 supports variables within your Google documents. You can include text that frequently changes and appears often in your documents as variables. Variables are also useful for providing information that is updated automatically, such as the current date. Variables are also very useful when single sourcing (using the same source document to generate different versions of a document) - you can quickly setup different targets with different values for a certain variable such as "company name".

Variables are also used by masterpages to control how to convert topics into output files.

Snippets (aka. conref:s)

Snippets are short documents that you want to reuse and include into topics when you generate output. Snippets are simply regular hyperlinks with a prefix "include:", i.e. to include a snippet into a topic you would create a hyperlink with whatever text you like but you would prefix that text with "include:".

The add-on has a special menu option to create these special snippet links. Note: If the snippet link is alone in a paragraph, the whole linked topic is included. If the hyperlink has text around it, only the text of the first paragraph in the linked topic is included. Nested snippets are supported, as well as snippets with images.

Conditional text (filter values, aka. filter tags)

The add-on supports conditional text within your Google documents. You can include text that frequently changes and appears often in your documents as variables. Variables are also useful for providing information that is updated automatically, such as the current date. Filter values (conditional text) are very useful when single sourcing (using the same source document to generate different versions of a document) - you can quickly setup different targets excluding or including content marked as conditional.

Projects

You can organize your content using projects. A project is simply a Google Drive folder with the extension ".project". Within the project folder, you will find two other folders. The Topics folder, into which all the real topics are placed, and the Support folder, which contains a number of support files that are used by Docs365 to compile the project into an output file, e.g. PDF.

Output

The add-on takes projects or individual Google Docs documents and compiles them into different output files.

Table of Contents

You add structure to your project with a Table of Contents (TOC) document. TOC documents are placed in the Support folder of a Project folder. A TOC tells the Docs365 project compiler which documents and in which order the documents should be placed in the generated output.

Targets

A target is a support file that tells the Docs365 compiler what kind of output should be generated from a project. Target documents are placed in the Support folder of a Project folder.

A project can contain more than one target, ie. you can generate different kinds (PDF, MSWord, Gdoc) of output from the same source documents.

Masterpages

Masterpages are used when generating single file output files, eg. PDFs and Google Docs. With a masterpage you can add a TOC, an index, headers or footers to the generated document.

Masterpages documents are plain Google Docs documents (but with the extension .master), you use different variables to control where things like the TOC and the Index should be placed in the new generated document. Masterpages are always placed in the Support folder of the project.

Index

Docs365 allows you to add indeces to your generated output, e.g. PDF

An index is created by adding index keywords to the content. The Docs365 compiler will later extract these keywords and produce an index section in the generated file. You insert index keywords using regular Google Docs comments. The text of the comment should be formatted like below.

index=key1:subkey1; key2:subkey2; key2:subkey2

 

More on conditional text

Docs365 version 1.1 enables conditional text in Google Docs. Our solution is mimicked by conditional text (profiling) support in the DITA standard.

Sets of paragraphs, parts of paragraphs as well as Docs365 TOC entries can be marked with four different types of filter tags (aka. filter values).

  • Audience
  • Platform
  • Product
  • Revision

Filter values are defined per project by a new Docs365 support file type, “filtervalue sets”, similar to the Docs365 “variablesets”. For our samples below, you would use a filtervalue set support document in Docs365 and define two audiences – “Marketing” and “Support” as well as two products – “Windows” and “Apple”.

At compile time, you tell the compiler to either include or exclude the text marked with the different tags. This is done by with the new “Filters” tab of the Docs365 Target editor. The TOC editor has been improved with a tab for filters in the TOC node dialog as well as a tab for previewing the TOC with filters turned on. The Topic details “editor” in the Docs365 main UI now allows you to preview a topic with filters on or off.

There are two kinds of control markup in Google Docs, one for sets of paragraphs and one for text within a paragraph. The Docs365 Docs add-on will soon include support for inserting this markup. It would be great if Google Docs would allow custom meta-data to be added to text but it doesn’t so we are stuck with this “in-text” markup.

Below is a sample of paragraphs in a Google Doc marked for the “Marketing” and “Support” audience. The gray text is part of the document but is the special control text that Docs365 uses to mark blocks of text. This gray text is always removed by the compiler.

This is text before the conditional text.

Audience{ Marketing, Support

This is a paragraph marked for the Marketing and the Support audience.

This is another paragraph only for the eyes of Marketing people.

}Audience

This is text after the conditional text.

Here is a sample of text within a paragraph in a Google Doc marked for the “Marketing” audience.

This is text before. {a:Marketing}This is text for marketing eyes.{:a} This is text after the marketing text.

This is text before. {p:Windows}This is text for the Windows platform.{:p} This is text after the conditional text. {p:Apple}This is text for the Apple platform.{:p}

Audience in-text syntax. “tags” below is a comma delimited list of filter values.

{a:tags}text text text{:a}

Platform in-text syntax:

{p:tags}text text text{:p}

Product in-text syntax:

{pr:tags}text text text{:pr}

Revision in-text syntax:

{r:tags}text text text{:r}

Some of the UE sections

Common snippets section

You have a personal Docs365/Common/Snippets folder that can contain small documents with sentences or paragraphs you often want include into documents. This section lists all those "snippet" documents. Use options here to quickly import content.

The Project TOC section

This section shows the project TOC of the project the topic is within. Clicking on one of the topics in the TOC opens a menu. Use the options in the menu to insert a link to the selected topic or open a new tab to edit the topic.

The Topics section

This section lists all topics in the project the viewed topic belongs to. Clicking on one of the topics opens a menu. Use the options in the menu to insert a link to the topic or view the topic. This section makes it easier to create links between topics in a project. You can also insert "include links" , these links will replace the link with the linked topic when you generate output using any of your targets.

The Stylesheets section

This section lists all Docs365 stylesheets in the project the topic belongs to. Clicking on one of the stylesheets opens a menu, use the menu to apply a stylesheet to the topic or to view the stylesheet with the full Docs365 site.

The Styles section

This section lists all styles in the currently applied stylesheet. Clicking on one of the styles opens a menu, use the menu to apply a style to the current selection.

The Insert a variable section

This section lists all variables defined in the project the topic belongs too. Clicking on one of the variables opens a menu, use the menu to insert the chosen variable into the topic.

Conditional text section

This section lists all filter values defined in the project the topic belongs too. Clicking on one of the values opens a menu, use the menu to wrap selection with the selected filter value.

Targets - generate output

This section lists all targets defined in the project the topic belongs too. Clicking on one of the targets opens a menu, use the menu to compile the topic using the selected target.

Next Document Link

This section allows you to create extra large documents by linking them into a chain of documents. This is an alternative to using full-blown Docs365 Table of Contents documents (TOCs).

The Images in docs section

This section lists all images and drawings in the current document. Use this section to resize, export, and/or change image attributes such as "title", "link" and "description". You can modify one or many images, for example select a few and make them the same size. You can also export individual images as well as drawings to external image files copied to your drive.

The Common Images section

This section lists all images in your Docs365/Common/Images folder. Place images you often want to include in this folder.

Group images section

This section lists all images in your [[shared folder]]/Common/Images folder. Use this to share images with your group that they often need to insert into documents.

Group sharing folder settings

You can share common resources (e.g. snippets, headers, templates and images) with a group of people by setting up a shared folder. This shared folder should have four subfolders - Snippets, Documents, Images, Headers. This sidebar section allows you to select the folder that has been shared with you. Hint: you have a personal Docs365/Common folder with the same subfolders for the same kind of resources, one quick way to allow people to use your templates is to share this folder with the group.

Doc templates

This section lists all document templates in your personal Docs365/Common/Documents folder. Use options here to quickly make a new document from the selected template.

Shared group templates

This section lists all document templates shared with you via the [[shared folder]]/Common/Images folder. Use options here to quickly make a new document from the selected template.

Headers

This section lists all headers and footer templates in your personal Docs365/Common/Headers folder. Use options here to quickly pick a header or footer for the document.

System headers

This section lists some useful headers and footer templates that you can either copy to your own collection or just use as is.