WARNING: This server provides a static reference view of the NetKernel documentation. Links to dynamic content do not work. For the best experience we recommend you install NetKernel and view the documentation in the live system .

Documentation Editing Guide

This is a guide to the NetKernel documentation system.

Creating Documents

Documentation is written as plain/text and may be in any of a number of Wiki dialects. If no syntax declaration is made on the first line then MediaWiki syntax is the default. The following section has guides to each syntax.

Markup Reference Guides

Macro Guide

The NetKernel wiki engine supports extensible macro engines.

A number of "built-in" macro engines may be used with your documents to style xml, java source etc. For details see this reference guide.

You may also add your own Macro Engines.

Endpoint Macro

If you wish to include a human readable rendering of an endpoint's metadata you may use the "endpoint" macro containing the id of your endpoint

{ endpoint}endpoint.id{/endpoint}

Publishing Documents

Documentation is published in two phases. First a text file is made visible to the documentation system by creating an entry in res:/etc/system/Docs.xml in your module. Secondly individual documents can be structured into books by referencing them in res:/etc/system/Books.xml

Example

When you create a module with the new module wizard it will automatically construct the required Docs.xml and Books.xml in the module's etc/system/ directory and provide some stubbed out documents as a starting point.

res:/etc/system/Docs.xml

The documentation system creates a master index of documentation by searching all of the public spaces for resources called res:/etc/system/Docs.xml - this must be a documentation list with the following structure...

<docs>
  <doc>
    <id>doc:some:unique:id</id>
    <title>Some Title</title>
    <desc>Some description</desc>
    <uri>res:/the/path/to/my/document.txt</uri>
    <icon>res:/the/path/to/some/optional/icon.png</icon>
    <keywords>some,optional,indexing,keywords</keywords>
    <category>doc accessor</category>
  </doc>
  <doc>
    <id>doc:some:other:unique:id</id>
    <title>Some Other Title</title>
    <desc>Some other description</desc>
    <uri>res:/the/path/to/my/other-document.txt</uri>
    <icon>res:/the/path/to/some/other/optional/icon.png</icon>
    <keywords>some,other,optional,indexing,keywords</keywords>
    <category>..</category>
  </doc> ...
</docs>

The id entry must be system-wide unique so that documents can be linked and structured into books.

The category field indicates that the document should appear in the Component Reference Guide. Category is a space delimited list of categories. To indicate that this is a document you must include the value doc.

Other category labels include:

For example to list a document in the transport section you would have

<category>doc transport</category>

res:/etc/system/Books.xml

The documentation system presents structured books by searching all of the public spaces for resources called res:/etc/system/Books.xml - this must be a book list with the following structure...

<books>
  <book>
    <id>book:system:admin</id>
    <title>System Administration</title>
    <desc>The system administration documentation</desc>
    <author />
    <publisher />
    <date />
    <modified />
    <icon />
    <keywords />
    <toc>
      <item id="doc:sysadmin:title">
        <item id="doc:sysadmin:guide:doc:editing" title="Alternative Title" />
        <item id="doc:sysadmin:wiki:title">
          <item id="doc:sysadmin:wiki:ref:mediawiki" />
          <item id="doc:sysadmin:wiki:ref:textile" />
          <item id="doc:sysadmin:wiki:ref:confluence" />
          <item id="doc:sysadmin:wiki:ref:tracwiki" />
        </item>
      </item>
    </toc>
  </book> ...
</books>

Each item has an id attribute which is the reference to the document id. Items may contain further items in a tree thereby providing the structure of the book. If an item has an @title attribute it will be used as an alternative (usually shorter) title for the menu listing.

Books.xml can contain any number of book definitions but each book id must be globally unique.

Book

You may provide a book icon by specifying the tag in the declaration. Icons may be resources SOURCEd from your module's documentation space. For example

res:/resources/img/myicon.png

Modern browsers also support SVG so your icon can be a scalable vector SVG...

res:/resources/img/myicon.svg

If you don't have the artistic inclination to create your own icon you can also use Fontawesome icons like this...

fa-rocket

Linking

The documentation engine will detect and cross link document ids and system endpoint ids.

For example this document has id doc:sysadmin:guide:doc:editing it can be linked from any other document using wiki specific syntax...

Syntax Link Format
MediaWiki
[[doc:sysadmin:guide:doc:editing|Editing Guide]]
Textile
"Editing Guide":doc:sysadmin:guide:doc:editing

System identifiers may also be used as link ids. For example the Groovy language runtime has id GroovyRuntime and is linked to with

Syntax Link Format
MediaWiki
[[GroovyRuntime|The Groovy Runtime]]
Textile
"The Groovy Runtime":GroovyRuntime

System links will take you from the documentation application to the Space Browser. Here is a live link to the Groovy runtime endpoint in the space browser.

SVG Vector Graphics

The documentation system uses inline W3C standard SVG vector graphics for diagrams and line art. To see these images you must have a modern web browser that supports XHTML and native SVG rendering.

Image: Three interlocking Red, Green, Blue circles

If you do not see the example image above, please contact your browser vendor and ask them for W3C standard SVG support or download one of the following standards complient browsers: Firefox, Opera

Please note, Microsoft Internet Explorer does not implement W3C standard XHTML nor SVG vector images and so is incapable of correctly viewing this W3C standards complient documentation correctly - please upgrade to one of the browsers suggested above

Embedded Images

Make an entry for the image resource in your module's etc/system/Docs.xml file. Like this...

<doc>
  <id>doc:mymodule:some:image</id>
  <uri>res:/path/in/your/modules/space/to/your/docs-n-images/some-image.png</uri>
</doc>

The is the resource's identifier within your module's address space. Note this does not have to be exported to the Front-End fulcrum - it only has to be resolvable within the same public as your other document resources.

This "document entry" will be aggregated into the set of all document id's and so be a known resource in the NK document system.

The documentation system provides a useful public REST service /doc/source/[document identifier] which serves the raw binary stream of any specified document identifier in the doc system.

Its operational pattern is to lookup the full resource identifier for a given document id, it also discovers the resource's home address space. It then performs a wormhole request for the resource and serves it as a BinaryStream.

It follows that you can get direct wormhole access to images from deep inside your module.

So in a document, here's how we might embed "some-image.png" (as registered in the example entry above) in a document...

{image}/doc/source/doc:mymodule:some:image{/image}

It follows that you can use this service directly as the URL in an HTML image link too. Here's the same thing done with raw HTML...


Wiki Resource Model Library

The documentation system is built on the Wiki resource model library.

Terminology

The terminology used to describe documents follows standard W3C / IETF best practice. The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL, when EMPHASIZED, are to be interpreted as described in IETF RFC 2119.