December 2, 2015

Pretty Project Description With CommonMark

pSeven provides several opportunities to make projects and workflows more clear to users. In the first place, we speak of project descriptions, workflow descriptions and workflow annotations. After these features had been added to pSeven, users have had an option to add descriptive information to their projects and workflows in plain text format. Plain text is simple, easy to read and write but it has several problems. The most noticeable difference between plain text and HTML is that HTML can contain images and hyperlinks. It also allows to use text formatting and to organize information better.

Why Markdown and CommonMark?

When we decided to provide our users with the capability to add rich text descriptions, Markdown was the logical choice. It is a lightweight markup language with plain text formatting syntax designed so that it can be converted to HTML and many other formats. However its syntax gets ambiguous in certain cases, so the final decision was to use CommonMark - a compatible and strongly specified implementation of Markdown.

A brief introduction to writing CommonMark is available in pSeven when you create a new project:

Main Features of CommonMark

Basic section structure in CommonMark is created by prefixing headers with hash (#) symbols. You can also use asterisks (*) and underscores (_) if you want to emphasize some important text.

Also, you can create links using the [link text](link target) syntax. The target can be an external resource (http://datadvance.net), a page in pSeven user manual (?/doc/index.html) or a project file, for example: (./workflow_name.p7wf), (./report_name.p7rep), (./samples/sample.csv). If the file can be edited in pSeven (like workflows and reports), it will be opened in pSeven when you click the link in project description; otherwise, a system application will be used.

To insert an inline image, you can use the following syntax: 

Usage

Examples of using CommonMark formatting can be found in pSeven example project descriptions. On the Workspace screen, you can switch to the Welcome tab, click Examples and select General Examples from the list.

The screen will switch to the project description automatically.

Editing a Project Description

To edit a project description you can click the “Edit description” button (appears when your mouse cursor hovers the description) or simply open the project README.md file from the Project pane.

Both actions will take you to the pSeven Markdown editor:

pSeven Markdown editor window is divided into two parts: the Markdown text editor as such and the rendered HTML. All changes you make in the top pane are immediately rendered to HTML in the bottom pane. When you click OK, all your changes are saved and the project description is reloaded.

Editing a Workflow Description

Workflow descriptions also can be edited, and you can use CommonMark to write them as well. To edit a workflow’s description, open the Workflow configuration dialog:

The workflow description is edited in the top pane of the General tab with the pSeven Markdown editor::

To show the workflow description in Edit, push the “Workflow description” button on the graph toolbar:

Workflow Annotations

Workflow annotations can also contain text formatted with CommonMark. To start editing an annotation just double-click it. Click outside annotation to stop editing and apply changes.

What about HTML?

HTML markup can be included in a CommonMark text, so in fact, you can use pure HTML wherever CommonMark is allowed. If you have experience with HTML editing, it may be even more convenient.