wiki:Documentation

This document explains how to create a documentation for a CrypTool 2.0 component for the new online, XML based, documentation system.

First, create (by using Visual Studio) a new xml file inside the C# project of the component which you want to documentate. Select this xml file in the "Solution Explorer" and make sure, that its "Build Action" setting is set to "Resource". The following picture shows how this can look like:

Now, open the main C# sourcecode file of the component (i.e. the file which contains the class with the "PluginInfo" Attribute). Take a look at the PluginInfo Attribute. It looks like this:

[PluginInfo("Cryptool.Plugins.Cryptography.Encryption.Properties.Resources", false, "PluginCaption", "PluginTooltip", "SDES/DetailedDescription/doc.xml", "SDES/icon.png", "SDES/Images/encrypt.png", "SDES/Images/decrypt.png")]

Important for us is the fifth parameter (which is "null" in this case). You have to insert the path to the new XML file as a string there. For the SDES Plugin, this path is "SDES/DetailedDescription/doc.xml" (note the fact, that the path must contain the assembly name).

Now, CrypTool 2.0 knows where to find the documentation file of the component. What's left is filling the XML file with appropriate content.

Structure of the XML file

Open the new XML file and paste the following template code into it:

<?xml version="1.0" encoding="utf-8" ?>

<documentation>
  <language culture="en"/>

  <introduction lang="en">
  </introduction>

  <usage lang="en">
  </usage>

  <presentation lang="en">
  </presentation>
  
</documentation>

The first XML Element "language" is to tell the doc parser, for which languages the documentation page should be generated. The template only supports english. If you additionally want to support german, just add <language culture="de-DE"/>. Please note, that it is required to always support at least the english language, or else the doc file will be ignored.

The xml file consists of three sections. You are free to fill them with formatted (see below) content. The different sections fulfill the following purposes:

  • Introduction: Should explain something about the purpose and maybe the history of the component or its underlying technique.
  • Usage: Should contain some instruction on how to use this component in CrypTool 2.0.
  • Presentation: Should explain something about the visual presentation of this component (if available).

All of these sections are optional and can be omitted if appropriate.

You can define each section multiple times with different "lang" attributes. If you define one of these sections in some language without defining the language with "language" XML element, as described above, the doc parser will ignore that language. So the "language" element is some kind of switch for activating the language.

Formatting the sections content

When filling the sections with text, you can use several XML tags to format it. These are listet below:

  • <b> bold </b>
  • <i> italic </i>
  • <u> underlined </u>
  • <newline/> for defining the end of a line.
  • The "enum" tag, which enumerates elements given by "item" tags (see below).
  • The "list" tag, which lists elements (unordered) given by "item" tags (see below).
  • <docRef item="Cryptool.TextInput.TextInput"/> to reference the documentation of another CrypTool 2.0 component
  • <external ref="http://en.wikipedia.org/wiki/Main_Page"/> to reference external URLs.
  • <img src="TextInput/Documentation/Demonstration.png"/> to include images (see below how to handle the image file inside the project).
  • <section headline="A section"> to structure the document further.

This is how the "introduction" section can look like:

  <introduction lang="en">
    TextInput is a <b>very</b> useful component... <newline/>
    <img src="TextInput/Documentation/Demonstration.png"/>
    <section headline="New Section">
      This demonstrates the capability to create sections.
      <newline/>
      <enum>
        <item>This</item>
        <item>demonstrates</item>
        <item>the enumeration</item>
        <item>capability!</item>
      </enum>
      <list>
        <item>This</item>
        <item>demonstrates</item>
        <item>the (unordered) listing</item>
        <item>capability! <b>Formating</b> is also possible! </item>
      </list>
    </section>

    <section headline="And another section">
      External links are possible: <external ref="http://en.wikipedia.org/wiki/Main_Page"/>
      <newline />
      External links with a link text are possible, too: <external ref="http://en.wikipedia.org/wiki/Main_Page">Click here!</external>
      <newline />
      Internal links are possible: <docRef item="Cryptool.TextInput.TextInput"/>
    </section>
  </introduction>

When using the "img" tag, you have to make sure, that the referenced image file is appropriately integrated into the components C# project. So, when referencing the path "TextInput/Documentation/Demonstration.png", the png file is contained in the "Documentation" directory. Like with the XML file, make sure that the "Build Action" of the png file is "Resource", or else the doc parser can't read it.

It is also possible to define tables with <table> <tr> <td> and <th> tags:

    <table border="1">
      <tr>
        <th>Header 1</th>
        <th>Header 2</th>
      </tr>
      <tr>
        <td>row 1, cell 1</td>
        <td>row 1, cell 2</td>
      </tr>
      <tr>
        <td>row 2, cell 1</td>
        <td>row 2, cell 2</td>
      </tr>
    </table>

References

It is also possible to include a list of (external) references in the documentation xml. There are currently two kinds of references: Book references and link references. While the first one is described by an author, a publisher and the name of the bbok, the link reference is described by a link (i.e. an URL) and a caption, which describes the linked content.

The reference section can look like this:

<?xml version="1.0" encoding="utf-8" ?>

<documentation>
  <language culture="en"/>
  <language culture="de-DE"/>

  .......

  <references>
    <linkReference>
      <link lang="en" url="http://en.wikipedia.org/wiki/Text_display"/>
      <caption lang="en">Text Display</caption>
      <link lang="de-DE" url="http://de.wikipedia.org/wiki/Text"/>
      <caption lang="de-DE">Text Anzeige</caption>
    </linkReference>

    <bookReference id="LordOfTheRings">
      <author>John Ronald Reuel Tolkien</author>
      <publisher lang="en">Harpercollins UK</publisher>
      <publisher lang="de-DE">Klett-Cotta</publisher>
      <name lang="en">The Lord of the Rings</name>
      <name lang="de-DE">Der Herr der Ringe</name>
    </bookReference>
  </references>
  
</documentation>

As you can see, every reference can be described in several languages.

You can give references an ID to reference them in your description text (i.e. in one of the three sections "introduction", "usage" and "presentation". You can do this by using the <ref id="LordOfTheRings"/> tag.

Last modified 6 years ago Last modified on Feb 27, 2013, 1:08:33 PM

Attachments (2)

Download all attachments as: .zip