Boost Quickbook Support Extension

From the Boost.Quickbook website:

QuickBook is a WikiWiki style documentation tool geared towards C++ documentation using simple rules and markup for simple formatting tasks.

This Visual Studio Code extension provide some simple language support to ease the task of authoring Boost.Quickbook(source) files.

It is not endorsed, published, approved or peer-reviewed by the Boost community, or anybody represented by the community. I have simply written it for myself to use - and put it out in the ether in case somebody else may find it useful too.

It is called "Boost Quickbook Support" because Quickbook is a Boost-published language/tool, and when I google "Quickbook" on its own, the search engine assumes I mean accounting software.

• The GitHub repository lives here: github.com/JBouwer/boost-quickbook-support

Features

• Syntax colouring

• Bracket/Quote matching

• Code folding
  
  

• Simple preview generation
  

Requirements

For the preview feature to work, you need a quickbook executable - either accessible within your $PATH, or explicitly specified in the quickbook.preview.pathToExecutable setting.

Extension Settings

• The executable's command options (see quickbook --help) when generating the preview, are represented by equivalent settings. Consult the Quickbook documentation for appropriate usage.

• File System Paths
  All filesystem path settings (i.e. to be passed as command-line options to quickbook, when generating the preview), can be specified relative to the VSCode workspace directories;
  These settings are processed as follows:

  1. The specified path is quoted and tested as is - if it exists, it is used.
  2. Otherwise the specified path is pre-pended in turn by each of the workspace directories - if it exists, it is used.
  3. Otherwise the specified path is quoted and used as specified.

• Local Images with a relative path
  By default, the extension's preview will temporarily adjust local relative image URI's (i.e. Quickbook [$ ...] directives with a relative path), by rooting image paths to the directory where the image may actually be found.
  (See FAQ #5 & #6 for rationale.)
  These directories are are searched in the following order, and can be included/excluded from the search:

  Directory	Setting Heading	Setting Name
  Explicit image directories	"Process Image Path Directories"	quickbook.preview.processImagePathDirectories
  Include directories specified with "Include Paths" (quickbook.preview.include.path)	"Process Image Path Includes"	quickbook.preview.processImagePathIncludes
  Workspace directories	"Process Image Path Include Workspace"	quickbook.preview.processImagePathIncludeWorkspace
  The directory of the source Quickbook file (i.e. the file that is being previewed).	"Process Image Path Relative"	quickbook.preview.processImagePathRelative

All the above directories, when enabled, are also implicitly trusted to access local resources. See Security below for more.

Security

The WebView API documentation component used to display the preview panel are very restrictive with regards to what resources can be accessed. In short:

• Any external resources needs to be explicitly trusted with the "Content Security Policy".
• Local resources:
  • Needs to be accessed with a special vscode-resource: scheme.
  • The scheme also needs to be explicitly trusted with the "Content Security Policy".
  • The root directories that contain local resources, need to be explicitly trusted, by adding them to the trusted list WebviewOptions.localResourceRoots.

See the WebView API documentation for more on this subject.

This extension provides the following features to accommodate the above requirements.

• Content Security Policy
  The quickbook generated preview HTML is injected with a <meta http-equiv="Content-Security-Policy" content="****"> directive, where the **** part is replaced by the contents of the Security: Content Security Policy (quickbook.preview.security.contentSecurityPolicy) setting.

  This setting defaults to "default-src vscode-resource: https:;" - thus allowing to access local (trusted), and https: resources.

• By default, the extension's preview will temporarily adjust the scheme of all local image URI's (i.e. Quickbook [$ ...] directives with a local path) to access the image with the "vscode-resource:" scheme, for rendering in the preview.
  This can be prevented by setting the Security: Process Image Path Scheme (quickbook.preview.security.processImagePathScheme setting to false.

• All of the directories that are searched for images (See Local Images with a relative path above), are implicitly added to the trusted list.

• The following settings will add their respective directories to the trusted list (WebviewOptions.localResourceRoots):

  • Security: Trust Source File Directory (quickbook.preview.security.trustSourceFileDirectory):
    When enabled (default), the directory of the source file (i.e. the file being previewed) is trusted.
  • Security: Trust Workspace Directories (quickbook.preview.security.trustWorkspaceDirectories):
    When enabled (default), all of the workspace directories are trusted.
  • Security Trust Specified Directories (quickbook.preview.security.trustSpecifiedDirectories):
    When enabled (default), all other setting-directory-paths are trusted;
    These include:
    • Boost Root Path (quickbook.preview.boostRootPath)
    • CSS Path (quickbook.preview.CSSPath)
    • Graphics Path (quickbook.preview.graphicsPath)
    • Image Location (quickbook.preview.imageLocation)
    • Include Paths (quickbook.preview.include.path(s)).
  • Trusted Additional Directories (quickbook.preview.security.trustAdditionalDirectories)
    A manually entered list of additional paths to trust.

In addition:

• Embedded Graphics
  All graphics (callouts etc.) embedded by quickbook into the preview html will be implicitly post-processed to be accessed with the vscode-resource: schema. This will still require the Security Trust Specified Directories (quickbook.preview.security.trustSpecifiedDirectories) setting to be enabled to work - in order to trust the Boost Root directory.

• Stylesheet (CSS)
  Any stylesheet specified with the CSS Path (quickbook.preview.CSSPath) setting will be implicitly post-processed to be accessed with the vscode-resource: schema.

Known Issues

This extension is not bullet proof. It is only intended as the next step up from a pure text editor - not as a complete documentation writing tool.

Currently it suffers from the following caveats. See the GitHub Issues Page for more.

• Bracket & Quote matching does not recognise escaped characters:

  e.g.
  [myTemplate includes a \] character]
  does not match correctly on the last ].

  Explanation

  The current bracket matching is simply specified inside the language-configuration.json file. I don't know how to do specify the concept of an escaped character in there - if possible at all.

• Post-processing of preview

  This is way out of my traditional field of expertise - so please bear with me whilst I try and catch al possibilities...

  The way it works is roughly as follows: (See processPreview in src/QuickbookPreview.ts)

  1. The quickbook generated preview text is scanned with a suitable REGEX to find all link contenders - which are then divided into pre, uri & post named (regex) groups.
  2. All of those are then further filtered to only process links that I have actually confirmed to need processing.
  3. Only the applicable links are then processed, and then re-assembled as:
     pre + processed(uri) + post

  Note that:

  1. I'm actually running blind as to exactly what needs processing
  2. I try to err on the conservative side

  This will (and have) lead to some oversights.

  Don't hesitate to report any examples of html that I may have skipped!
  You can find the pre-processed html in the preview file that is reported with the quickbook command line on VSCode's Output panel: Look for the --output-file "..../out/preview.html" option.

  I've opened Issue #9 for reporting of any such oversights.

FAQ

Some answers to potential problems can be found here.

Release Notes

The CHANGELOG will list details of what changed within each release.