Today we updated the documentation for or Display Table Macro and Display List Macro! These macros are part of projectdoc addon for Confluence.

Both macros allow to select on projectdoc documents within the Confluence wiki, using a Lucene search syntax. The Display Table Macro renders the properties and sections of a document as columns. The Display List Macro is a simplified version bound to the task of rendering document names and optionally short descriptions as definition lists, unnumbered, or numbered lists.

You specify queries like this:

SELECT PropertyOne, PropertyTwo, PropertyFour
WHERE PropertyOne = "Some String" AND 
        (PropertyTwo = "Another String" OR PropertyFive = "Something")
SORT BY PropertyOne, PropertyThree

Note that this is pseudo syntax. The values for SELECT, WHERE and SORT BY are passed to the macros as parameters.

Here are some screenshots to give you a visual impression:

You may have a look at the updated Prezi presentation: projectdoc Macros. This presentation is a brief overview over the macros provided by projectdoc.

Today we updated the documentation for or Transclusion Macro! The macro is part of projectdoc for Confluence.

This macro transcludes content from wiki pages. It supports the following features in combination with the Section or the Content Marker Macro:

• Transclude multiple elements from a page
• Transclude by ID or tags
• Link to the transcluded content in author mode
• Transpose heading levels
• Replace placeholders with values
• Render a warning if nothing can be transcluded due missing page or content

Interested? Please check out the documentation of the Transclusion Macro!

For detailed information about all projectdoc macros, please refer to the list of macros.

Or have a look at the updated Prezi presentation: projectdoc Macros. This presentation provides a brief visual overview over the projectdoc macros.

Note that projectdoc is a commercial add-on for Confluence that provides an alternative approach. If you are looking for free add-ons, Atlassian provides a number of macros supporting transclusion or embedding content:

• Excerpt Include Macro and Excerpt Macro - the native Confluence macro to use for transclusion.
• Include Page Macro - includes a complete page into the document.
• HTML Include Macro - includes a HTML document into the document.
• View File Macro - embeds an Office or PDF document into the document.

projectdoc for Confluence is scheduled to be released by the end of this month. Our documentation effort currently concentrates on the addon’s macros.

Today we finished the documentation for 19 macros or the more of 40 macros provided by projectdoc.

The macros with updated documentation are:

Tip Box Macro

Renders a box with a tip for the reader.

Warning Box Macro

Renders a hint to warn the reader about something.

Fault Box Macro

Renders a box containing a fault message reported by a team member for the author.

Section Macro

Renders a section, if the body is not empty. Allows to transclude the content.

References Box Macro

Renders a box with references to further information.

Question Box Macro

Renders a box containing an open question.

Pending Box Macro

Renders a box containing a pending message to be handled later by the author.

Note Box Macro

Renders something to note by the reader.

Iteration Macro

Selects an iteration phase from a fixed set of stages.

Info Box Macro

Renders a box containing an info message.

Hide From Anonymous User

Hides a text fragment from an anonymous user.

Hide From Viewer Macro

Hides a text fragment from a user that has no edit permissions.

Feedback Box Macro

Renders a box containing a feedback message from a reader with write privilege.

Example Box Macro

Renders an example within a box.

Caution Box Macro

Renders a box containing a caution message.

Deprecated Box Macro

Renders a box containing a deprecation warning for the reader.

Document Properties Marker Macro

A table containing document properties. Three columns: name, value and meta data to a property.

Content Marker Macro

Marks a piece of content within a document. This content can be referenced for transclusion.

Definition List Macro

Renders term and definition information as a definition list. Currently Conflucene does not easily support authors to write definition lists. But definition lists allow to render this form of information efficiently.

For detailed information about these macros, please refer to the list of macros.

Or have a look at the updated Prezi presentation: projectdoc Macros. This presentation provides a brief visual overview over the projectdoc macros.

Macros are the base for developing page blueprints for Confluence with projectdoc. projectdoc provides more than forty macros to support you and your team to collaborate on creating agile documentation more easily.

Today we started a short presentation with Prezi and a video to give you an overview over the macros provided by the projectdoc add-on version 1 for Confluence.

Our free add-on Project Documentation Macros for Confluence celebrates its 100th download today!

The add-on currently provides two macros: a Definition List Macro (e.g. to create glossaries) and a Hide From Anonymous User Macro (e.g. to not display the Create from Template Macro to user's not logged in)

You may install the free addon from Atlassian Marketplace!

If you are looking for more macros and templates to support your effort in creating good project documentation, please have a look at our projectdoc add-on! It will be available from Atlassian Marketplace soon.

Today I had to create HTML element identifiers with one of our macros for Confluence. I realized that our way of generating HTML 4 IDs had not been compatible with the solution Confluence offered. So I tried to find the service class that runs the HTML element ID generation.

It turned out that it is easily accessible via the conversation context. :-)

HTML 5 vs HTML 4

First I had been confused since the IDs generated by Confluence for their headings contained non-ASCII characters. But Confluence creates HTML 5 content and therefore identifiers simply must not be empty and not contain spaces.

The value must be unique amongst all the IDs in the element's home subtree and must contain at least one character. The value must not contain any space characters.   

 

HTML5 - A vocabulary and associated APIs for HTML and XHTML. 3.2.5.1 The id attribute

So I removed our HTML 4 compatible ID generation code.

Confluence's HTML ID Creator

I looked for the service class and finally found a little helper class in com.atlassian.confluence.content.render.xhtml.HtmlElementIdCreator, which is an implementation of com.atlassian.confluence.content.render.xhtml.ElementIdCreator.

This implementation makes it easy to actually create unique identifiers. If a non-unique title is encountered, the helper adds a dot with a running number (e.g. MyPage-MyTitle.1 for the second title), ensuring its uniqueness.

 

Note the basic pattern:

 

[PageTitle]-[NameofHeading][.counter]?

But, as a Confluence user, you will normally not get in touch with this details. If you edit a link via the visual editor, you simply specify page title and heading on the Advanced tab.

It is very easy to access an instance of ElementIdCreator from the conversion context.

final PageContext pageContext = conversionContext.getPageContext();
final ElementIdCreator creator = pageContext.getElementIdCreator();

Note that the documentation to getPageContext() says that it is almost deprecated, but I found no other way to access the creator instance.

Conversion is straight forward, with basis being a reference to a character sequence you want to transform to an HTML 5 identifier:

final String html5Id = creator.generateId(basis);

If you are not interested in ensuring uniqueness of your ID, you may use the static method of HtmlElementIdCreator:

final String html5Id = HtmlElementIdCreator.convertToIdHtml5(alreadyUniqueId);

Conclusion

Using the implementation of the ElementIdCreator interface helps to integrate your macro generating identifiers smoothly into Confluence.

The Section Macro from our projectdoc for Confluence add-on use this facility since version 1.1.0 (PDAC-242).

Please visit projectdoc for Confluence for more information on projectdoc or watch our new video introduction to projectdoc.

I’m happy to announce the new video to introduce projectdoc. We have already provided a few screencasts, but this video’s intend is to provide an overview over projectdoc for Atlassian Confluence.

This is in advance to the release of projectdoc. Chances are good that we will push the projectdoc addon to the Atlassian Marketplace for review by Atlassian on Friday. So with a little bit of luck version 1 of projectdoc for Confluence will be available by the end of October – and to be bold: 2014!

The video is based on a Prezi presentation and is available on YouTube (sound alert). On the projectdoc Wiki page, you’ll also get a transcript that delves a little bit deeper into the catch words.

You will learn about:

• Properties & Sections
• Document Types
• Guided Writing & clutter-free Reading
• Automatic Lists
• Single Sourcing & Transclusion
• Macro Structures
• Space Hierarchies

And we hope that you will agree that with projectdoc your documentation (aka technical communication) is

• easier to write
• easier to extend
• easier to reuse
• easier to navigate
• easier to search
• easier to read

And all of this while you are still in control to define your documentation architecture according to your requirements. This is important, since agile documentation demands to only create documentation that really supports your team and/or product.

You’ll notice that this is a low budget production. So please be gentle to the visuals … but we hope that a video will give you a much better introduction to projectdoc than wading through pages of text (although we also provide these).

We hope that projectdoc will help you to improve you documentation experience with your Confluence wiki!

Enjoy the video: Introduction to projectdoc!

We are happy to hear and to share that Red Hat has released version 1.5.0 of their fork of the Buildmetata Maven Plugin!

Congratulations!

The team at Red Hat managed to fix a couple of issues, improved the integration tests and further enhanced the SCM support. So their version of the Buildmetadata Maven Plugin is currently the most stable to be found on the planet!

The sources are available from the project's homepage at GitHub. Binaries can be downloaded via repository.jboss.org, Maven Central and Brew (the build system used internally by Red Hat).

And if you want to have a bigger picture of the work of the Red Hat team according to Kojak (which is Koji in a box and where the buildmetadata-maven-plugin plays only a minor role): Have a look at

Salim Badakhchani's talk: Kojak - Building software the Red Hat way!

The talk has been recorded at foocafe.

Just in case your are wondering: smartics of course continues the support of our version of the plugin. We plan to merge the improvements of the team at Red Hat into our stream of development soon (which reads: hopefully by the end of this year :) - since we are currently working eagerly to push out the first version of our new projecdoc Add-on for Confluence!).

The collaboration continues! :)