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
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.
-
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 toquickbook
, when generating the preview), can be specified relative to the VSCode workspace directories;
These settings are processed as follows:- The specified path is quoted and tested as is - if it exists, it is used.
- Otherwise the specified path is pre-pended in turn by each of the workspace directories - if it exists, it is used.
- 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.
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
Thequickbook
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), andhttps:
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)
).
- Boost Root Path (
- Trusted Additional Directories (
quickbook.preview.security.trustAdditionalDirectories
)
A manually entered list of additional paths to trust.
- Security: Trust Source File Directory (
In addition:
-
Embedded Graphics
All graphics (callouts etc.) embedded byquickbook
into the preview html will be implicitly post-processed to be accessed with thevscode-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 thevscode-resource:
schema.
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.
-
e.g.
[myTemplate includes a \] character]
does not match correctly on the last]
.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. -
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
insrc/QuickbookPreview.ts
)- The
quickbook
generated preview text is scanned with a suitable REGEX to find all link contenders - which are then divided intopre
,uri
&post
named (regex) groups. - All of those are then further filtered to only process links that I have actually confirmed to need processing.
- Only the applicable links are then processed, and then re-assembled as:
pre +
processed
(uri) + post
Note that:
- I'm actually running blind as to exactly what needs processing
- 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-processedhtml
in the preview file that is reported with thequickbook
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.
- The
Some answers to potential problems can be found here.
The CHANGELOG will list details of what changed within each release.