projectdoc Toolbox 1.9 Release Notes

Transclusion Cache, Report Support, Enhancements and Bugfixes, Support for Confluence 6.9

Today we released version 1.9 of the projectdoc Toolbox!

projectdoc is an add-on for Confluence supporting agile software development teams to collaborate on process, project, system, and product documentation. 

The name changed from projectdoc to projectdoc Toolbox. We hope this will make it more clear to potential users that projectdoc is a set of tools to support project teams to create their modular and agile documentation collaboratively with their Confluence wiki.

New and Noteworthy

The following changes may be the most interesting of this release.

Support for Confluence 5.9

The new version of projectdoc is compatible with Confluence version 5.9.

Transclusion Cache

For users that employ transclusion heavily, we added a transclusion cache that can be activated at space level. If you ask yourself "Am I using transclusions heavily?": If you have a few hundred documents that transclude documents transitively in depth 10, then yes, you'll take much advantage of this update.

Why didn't we activate for the whole instance per default? Caching always implies that you may have stale information. We provide a timestamp and an option to refresh the content for authors, but for typical usage scenarios where a document transcludes a multiple sections from a couple of documents usually does not call for caching.

With the help of the transclusion box authors will not only see transcluded content and jump to it by clicking on the name. The new version adds an extra edit button to open the document in an editor to apply changes quickly!

If you want to give it a try: Fragments Cache for Transclusions

Lucene Indexer

This version fixes some issues with the creation of the Lucene index and the document caches. After the Lucene indexer has finished, the document cache will now be cleared. Therefore there is no need to do this manually any longer.

Ancestor Searches

The doctype cache, which is required for the ancestor searches, did not always recognize when it has been cleared. As a result the queries selecting on ancestor properties has empty results.

With this release the cache checks on each access if a refresh is required.

Descriptive and Informative Abstracts

For teams creating documentation it is important to define the contents of the documents in advance. This is what the Description section on each document is for. Some documents need to distinguish between a description of the document and an informative summary of the content. The first is created in advance, the second after the document has been created.

We do not advice you to provide both sections for each of you documents. But lately it turned out for our documentation efforts that we sometimes need that informative summary and had no commonly defined space to put it. With this release most documents provide an additional space called Summary.

For more information on sections common to most document types, please refer to Document Sections.

Transclusion Recursion Detector

Due to the focus on reuse with transclusion and the possibility to specify queries to transclude from documents in the result set, it has become more and more important to detect recursions in the transclusion chain. With this release we added support for such a detection mechanism.

Breaking Changes

The following changes are incompatible with the previous release.

Default for Exclude-Self

The Display Table and Display List Macro now have the document the macro is part of excluded from the result set per default.

In previous versions the default for 'Exclude Self' has been 'false'.

The reason for this change: The exclusion is the common case. Having the document launching the query included in the result set is rarely required.

Known Issues

This release has the following issues.

Blueprint Icons

The blueprint icons are not properly rendered in the Internet Explorer. Instead of the icon there is either the broken image link or no image at all.

There is an issue that tracks this problem

PDAC-561 - Display Blueprint and Space Blueprint Icons in IE and Edge Done

Upgrade Instructions

he following topics have to be considered for an upgrade to this version.

Compatible Doctype Add-on

Please note that we recommend to also update your free blueprint add-ons. Some of the add-ons also add new features or enhancements, but all have been tested to work with the projectdoc add-on in version 1.9.

Please check to update the following doctype add-ons:

List of Changes

The complete list of changes for this release.

The following changes are part of the latest projectdoc Toolbox for Confluence.

Key Summary T P Description
PDAC-527 Cache for Transclusions New Feature Blocker (migrated)

Modular documentation employs transclusions quite heavily. While referencing content is an alternative, readers enjoy a compiled document more. Therefore we need to provide means to enhance the speed of calculating a page that is heavily using transclusions.

One approach to enhance speed is to introduce caches. This should be our first strategy to tackle this problem.

PDAC-508 Replace Placeholders on Wiki Link New Feature Critical (migrated)

Allow to set placeholders to be replaced with space (and page) properties. Currently only a handful of @-marked placeholders are considered. Replace any placeholder defined with ${...}.

This will also help to reference versioned documents.

PDAC-558 Exclude Self Default New Feature Major

The default for the Display Table and Display List Macro for excluding self in the result set should be "true". This makes it safer for users and also is the natural default case.

PDAC-551 Summary for Informative Abstracts New Feature Major

The description is a descriptive abstract to introduce the reader in the structure of the document. It is used to help readers to determine whether or not the document at hand is interesting for their problem or not.

We also want a section to contain the informative abstract. Readers may read this summary and get all information of the document in a brief manner.

Team could therefore define the structure of the document in the description and collect information in the summary. This will support collaboration.

Not all document types need a summary. Categories, Tags, ... have descriptions and that is all they need. But each document with a topic-like intention should have a section called summary to host informative information.

PDAC-530 Refresh Document als kicks out Fragments from Cache New Feature Major

When the user invalidates an entry in the document cache, it should also be invalidated in the page fragments cache.

PDAC-529 Render last Update Timestamp on Transclusion Box New Feature Major

To make the last update of a transcluded fragment visible to authors, render the timestamp of the last update on the box around the transcluded content.

PDAC-528 Allow Transclusion Macro to switch off Cache New Feature Major

Allow the author to decide per transclusion if the cache should be used to lookup page fragments or not. The switch only controls the behavior of the macro, not that of macros' content that is transcluded transitively.

PDAC-525 Add Space Description Box for Space Creation Wizard New Feature Major

Allow to add a space description on creating a space with a wizard.

PDAC-510 Add Buildmetadata as Metadata New Feature Major

Buildmetadata created with the Buildmetadata Maven Plugin should be made available as metadata. Currently we do not need to have a human readable report, just the metadata to reference.

Each buildmetadata property name is prefixed by "buildmetadata.". It is the linearisation of the XML document that is stored inside the "JAR/META-INF/buildmetadata.xml". The properties file is not used (since the other keys are generated).

PDAC-507 Store Version Document in Blueprint Context New Feature Major

For later reference store the version document instance in the blueprint context by the key "projectdoc.pages.version". This will allow report generators to attach themselves to that version.

PDAC-506 Report Page Generation New Feature Major

Add support to add report pages. It should be easier to add information from external sources.

PDAC-519 Allow to select the Icon for the Space List New Feature Minor (migrated)

Allow to select the icon to be rendered as in a column of the space list rendered by the Space List Macro.

PDAC-554 Provide icons for refresh and edit links in transclusion boxes Improvement Critical (migrated)

Transclusions can render boxes around the transcluded content. These boxes provide a link to edit and refresh the transcluded content. These links shall be replaced by icons provided by Confluence AUI.

PDAC-553 Parent Macro Support for Ancestor Search Improvement Critical (migrated)

Like the Name List Macros the Parent Property Macro should also support ancestor searches.

PDAC-546 Detect Transclusion Recursion Improvement Critical (migrated)

If transclusion enters recursion the systems gets under heavy load until the stackoverflow is reached. We should detect this situation and stop transcluding once we reach a document we transcluded from before.

PDAC-526 Streamline Transclusion Semantics Improvement Critical (migrated)

The semantics of transclusions should be improved to:

  • a suppressed section suppresses all subsections
  • a suppressed section will also be suppressed as subsection
  • transcluded content on a transcluded page is untouched by the selection
PDAC-504 Support Import of Maven BOM Improvement Critical (migrated)

Import of Maven projects that use BOMs fail.

PDAC-557 Guard Create-Buttons with Hide Macro Improvement Major

All Create-Buttons have to be hidden if the user has only reading privileges.

Some templates already have this guard, but now we want all templates to provide it.

PDAC-555 Handle Sections with PDF Attachements as non-empty Improvement Major

Rendering attachments (e.g. PDF) in a section will render them as empty. They should be recognized as non-empty.

PDAC-552 Render Date with the Quote Macro Improvement Major

The Quote Macro renders the "Publication Date" property of a document instance. If this is not specified, it should render a generic "Date" property.

PDAC-543 Dismiss non existing Section gracefully Improvement Major

If the Document Properties Marker Macro delegates to document that lacks certain sections, we should not render an error box, but instead should render nothing.

If the user wants to be strict (and render a box on a missing section), she has to configure this behaviour via a space property.

PDAC-541 Not overriding Blank Document Properties Improvement Major

The document properties on the blank template should not override the standard settings of the space.

PDAC-537 Suppress Transclusion Box around Properties Table Improvement Major

If the user decides to select properties to be rendered in a table above the transcluded sections with the Transclude Documents Macro, the table is enclosed in a transclusion box. Since the whole hit is already rendered in such a box, the box is rendered twice.

It should be rendered only once.

PDAC-534 Rename Blank Space to Starter Space Improvement Major

'Blank Space' is misleading. We provide this space blueprint to get new users start with projectdoc quickly. The main aspect of the space is that it does not assume that users employ any document types (not even the core doctypes!). Therefore the Tags and Categories properties do not assume the use of the Tag and Category doctype and do not render a Name List Macro.

We should get this message more clear on the Space and Page Blueprint and rename the Space to 'Starter Space'. The name 'Blank Page' seems good enough. It is basically a blank page in the sense of projectdoc. If users would use the Core Doctypes they would use the Generic Doctype which integrates with the other Core Doctypes (e.g. Role, Tag, and Category).

PDAC-533 Allow to render Tour Table without Header Improvement Major

Add a parameter to suppress the table header rendered by the Tour Macro.

PDAC-531 Allow to render Display Table without Header Improvement Major

Add a parameter to suppress the table header.

PDAC-517 Default Template for Display Properties Macro Improvement Major

To make it easier to use the Display Properties Macro the mandatory Template property is now optional. If not specified, it now defaults to

$[Name] - ${Short Description}

If this does not meet the user's requirements, it can be easily changed (as always).

PDAC-513 Refresh Creates Page Tree Improvement Major

As a workaround run a refresh on the generated page tree whenever we create one.

It seems that the API we generate page by page does not work as expected. Sometimes we do not get properly created pages. At least they seem to pass the Lucene Indexer to late.

We should check if we could alter the use case to get a more performant solution.

PDAC-509 Allow Wrapping Content Marker Macro Improvement Major

Unfortunately the body is extended to create valid HTML. This makes it difficult to render HTML fragments. Therefore add a new property to the Content Marker Macro to wrap the content by another element. This is especially useful to add list elements.

PDAC-505 Section with Media Content Improvement Major

If the Section Macro contains media content, it does not render. This is because it regards the iframes used by Confluence to render media as empty.

We should check for iframes and assume that they are not empty to render sections that contain only a reference (via an iframe) to media content.

PDAC-503 On failed POM Import provide Error Message on Homepage Improvement Major

The problems encountered on importing a POM are currently only logged to the Confluence log file. We should add this to the homepage to inform the user who run the import immediately.

PDAC-502 Document Type Conversion Sort Order Improvement Major

Add documentation to the Sort By Property of Display Table, Display List, and Transclude Documents Macro. The Type Conversion feature is not obvious.

PDAC-501 Render Content Marker Macro Span only with Content Improvement Major

Render the span element of the Content Marker Marco only, if there is content. Also suppress the identifier if it is not specified.

PDAC-500 Enhance Error Report on Missing Nexus Configuration Improvement Major

The message of the Nexus Link Macro for signalling errors to the user is rather brief. We should add a link to the documentation to help users finding out what to do more quickly.

PDAC-499 Use Download URL of Distribution Management Improvement Major

Currently we try to derive the artifact repository URL from the release or snapshot repository of the distribution management of the POM. But the information we should use is the download URL.

downloadUrl: is the url of the repository from whence another POM may point to in order to grab this POM's artifact. In the simplest terms, we told the POM how to upload it (through repository/url), but from where can the public download it? This element answers that question.

https://maven.apache.org/pom.html#Distribution_Management
PDAC-550 Add Spacekey to Tooltip in Transclusion Box Improvement Minor (migrated)

Add spacekey to tooltip in link of transclusion box to transcluded page.

PDAC-532 Render Header of Display Table Improvement Minor (migrated)

The header rendered by the Display Table Macro should render inside a HTML thead element.

PDAC-540 Refresh Tree Action Fails Bug Blocker (migrated)

On starting the tree refresh action the browser reports a content encoding problem.

PDAC-547 Overriding of Field "Render As" in Document Properties Marker Macro does not work Bug Critical (migrated)

When via Space Property or via an Index Space (Delegat Space) the Space Property render-metadata-as is set to "definition-list" it can not be overwritten via "Overwrite Checkbox" in the Document Properties Marker Macro.

PDAC-544 Transclusion resolves CDATA Blocks Bug Critical (migrated)

Transclusion parsed the content and thereby translates CDATA content to text.

See https://github.com/jhy/jsoup/issues/406.

We have to preserve the CDATA block otherwise the code macro will not render the content correctly.

PDAC-539 Lucene Indexer fails to create projectdoc Document Cache Bug Critical (migrated)

If the projectdoc Document is created with the indexer, not all properties are rendered properly.

If the page tree is refreshed, this problem does not occur.

If the page is saved and the indexer runs, the problem does not occur.

PDAC-538 Doctype Cache gets lost Bug Critical (migrated)

The cache that stores the doctype information gets lost. This is okay, since it is a cache, but currently it is not able to refill itself.

The consequence is that ancestor searches (those based on the type of a property) will not work. The failure is an empty result set.

In any situation that invalidates the cache or its contents (low memory, restarts, redeployments, ...) the cache is required to get back to a valid state.

PDAC-524 Space Property 'suppress-transclusion' fails Bug Critical (migrated)

Setting the space property 'suppress-transclusion' to 'true' does currently not suppress transclusions.

PDAC-560 Unable to Escape Characters in Query Bug Major

If a value to query for in an exact match query contains a special character (e.g. a bracket), the query parser is unable to parse the input string successfully. The problem is that the user has to have the option to escape characters that have to be taken verbatim. The parser cannot, without any help, examine the input string and detect which spacial characters are taken as is and which have special meaning.

We therefore need the feature of escaping characters.

For instance: To find a document with an exact match containing brackets, the query looks like this:

$<Identifier>=[My Term (with brackets)]

PDAC-559 Remove Exclude Self for Transclude Documents Macro Bug Major

The Transclude Documents Macro does not allow to change the settings for exclude self for security reasons. Therefore the checkbox has to be removed from the macro configuration page.

PDAC-556 Getting Started Link broken Bug Major

The information for new users to get started with projectdoc has a link that points to a non-existing page.

It should link to www.smartics.eu/confluence/display/PDAC1/projectdoc+for+Confluence+V1

PDAC-549 Space Delegate Calculation broken Bug Major

The calculation of the delegate spaces is broken. The parent space (if not per incidence is the index space) is not taken into account.

PDAC-548 Display Table Macros Counter Column Conflicts With Calculation Columns Feature Bug Major

Activating the Counter Column in a Display Table Macro and using the Calculate Columns feature leads to a corrupt rendering of the table.

PDAC-536 Transclusion of Raw Text Bug Major

The transclusion macros do not transclude text outside of HTML elements. This is especially true of the content of the Section Macro is raw text.

PDAC-535 Definition List Renders illegal Names Bug Major

The display list renders the normalized original value instead of the normalized rendered value.

PDAC-523 First selected Property is rendered as Title Bug Major

Using the Transclude Documents Macro and using the Select Property, the first selected property is always rendered as section title.

Instead it should either check the status if the "Name as Heading" property and understand if a title is rendered with the Ids/Tags selection. If this is the case the table with properties should be rendered after the section heading but before the sections.

PDAC-521 "Name as Heading" renders Heading twice Bug Major

Setting the "Name as Heading" property of the Transclude Documents Macro will render the title of the document as heading twice, if there are properties selected. The Select property contains "Name, Iteration". No Ids or Tags selected.

The rendering of the second heading should check if a heading is already rendered and suppress the duplicate rendering.

In addition to that the level of the transcluded sections have to be increased by one level if the heading is rendered in front of the properties table.

PDAC-520 Selected Heading rendered with Numbering Bug Major

A user selects properties to be displayed in a table with the Transclude Documents Macro. The user selects name and iteration so that the name is rendered as a heading at a selected level.

Then the heading is rendered with a number even if no numbering is selected.

Expected is that the heading is not rendered with a number.

PDAC-518 Restricted Link in Tour Macro Bug Major

If the tour macro contains a link to a page the user has not access to, the whole table is not rendered.

Instead only the links to the page without access permissions should be skipped.

PDAC-516 User Space must not override all Properties Bug Major

Since user space properties are preferred they will also apply for information (such as space key or creation time) where they should not.

PDAC-514 Create-Template Buttons not removed Bug Major

The remove-Create-Template-Button feature does not remove the element any longer. This problem applies to the latest Confluence version (5.8.9).

PDAC-512 SNAPSHOT Access Bug Major

Snapshot artifacts cannot be downloaded from remote repositories.

The resolver does not cope with tagged snapshot versions. Therefore we have to tell the subsystem that the versions are not unique.

PDAC-545 Stacked box macros are rendered with wrong images Bug Minor (migrated)

When box macros are stacked the inner boxes are rendered with wrong images.

PDAC-522 Short Description rendered before Title Bug Minor (migrated)

Using the Transclude Documents Macro and selecting "Extract Short Description" will render the short description in front of the section title.

I would expect that it is shown after the title and before any other content. Are there use cases that expect the short description in front of the title?

Resources

Release Notes for the projectdoc Toolbox
Relevant information on changes to the projectdoc Toolbox for Confluence introduces by new versions of this app.
Glossary
Terms used in and defined for projectdoc.
FAQs
Questions and answers related to the projectdoc Toolbox and Confluence.