Docs

From Emergent

Jump to: navigation, search

Docs are simple but very helpful and powerful - a doc is basically a small document inside a project that can be used for any purpose. Docs are most useful for writing descriptions of simulations, instructions for customization or running, keeping track of scientific references, providing tutorials, and so on. You can link any object to a doc, which enables you to put the doc text right at the place it is most needed.

In addition to basic HTML and wiki-style formatting, these doc objects also support internal ta: links or URL's that can activate different objects within the project, call functions, and control what is displayed. Thus, you can use document objects to provide a "live" tutorial for running and controlling your project.

Contents

To create a doc

  1. click on the docs collection in the project
  2. right click, select New
  3. in the dialog, press Ok
  4. rename the new doc with a descriptive title

Editing a Doc

A doc can use many common Wikimedia wiki tags, as well as most common HTML tags (wiki tags are often easiest.) The simplest docs don't need any formatting at all (just enter plain text.) However longer docs will benefit from at least some formatting, such as section headings, bulleted and numbered lists, and italics and bolding.

To edit a Doc

  1. select the doc in the project tree
  2. in the panel, select the Doc Source subpanel
  3. enter or modify any combination of: plain text, wiki text, or html text
  4. when you are finished making changes, press Apply
  5. view the resulting formatted document in the Doc panel, to verify your edits, formatting, etc.

HTML and Wiki Formatting

Headings 

 = Level 1 Heading =
 == Level 2 heading ==
 (etc).

Lists

This is a bulleted list: 

* Item 1
* Second Item
* Third item

This is a numbered list: 

# Item 1
# Second Item
# Third item

Emphasis, Bold

For emphasis (italics): 

This word: ''important'' will be italicized

For bold: 

This word: '''bold''' will be bolded


Linking Docs

Docs in the doc collection can be helpful by themselves, especially if they are given descriptive titles. You can enhance the utility of docs by linking a doc directly to an applicable object. For example, you might write a doc called "Setting Network Parameters" which you might like to link directly to the network. A linked doc will appear (in read-only, formatted form) in a new subpanel of the object. (This is a view of the document, not a separate copy - if you edit the doc, the new content will automatically be displayed anywhere it is linked.) Note that an object can only be linked to a single doc; however, you can link a single doc to as many objects as you wish.

To link a Doc

  1. select the object in the project tree
  2. right click, and select Set Doc Link from the menu
  3. in the dialog, choose the doc you want to link
  4. press Ok

the linked doc will appear in a new Doc subpanel in the Panel for the object

URLs

Docs can contain Uniform Resource Locators (URLs) or "links". These can be any of the following:

  • standard html "a" links, which when pressed, will open an external application:
    • http: opens the user's browser (the most common type of link)
    • mailto: opens the email application
  • function calling - invoke a method on any project object
  • tab viewing - show/open the tab for an object
  • invoking another doc - navigate to another doc
  • showing a control panel - show a control panel tab

You can see examples of all these URLs in the tutorial project provided with Emergent.

Syntax Details

The full explicit ta:... path can be used, or, because ta: paths all start with a single period (.), if you just start the link with that, it will automatically translate it into a ta: path, using only the last part after last . as the name of the link. Only the first example shows both forms -- the rest use the simpler "short form".

NOTE: for any of these cases, you can always customize the link text by adding a "pipe" character and whatever text you want -- some examples shown below.

  • A link to an object -- the path after ta: is any valid css path to the object -- this will select the object in the viewer and bring up an edit panel for it: 
[[ta:.networks[0].layers.Output]] # long form, shows full path
[[.networks[0].layers.Output]]    # short form, shows up as just Output
  • A function (method) on an object -- will actually call this function directly! 
[[.data.InputData.StdInputData.GridView()]]  # link text is StdInputData.GridView()
[[.data.InputData.StdInputData.GridView()|Make GridView]] # link text is "Make GridView"
  • An edit panel with a given name (typically name of object being edited) -- this will activate that panel: 
[[.PanelTab.ControlPanel]]
  • An 3D view panel with a given name -- this will activate that panel: 
[[.T3Tab.NetworkView]]

[[.Wiki.Program]]
Retrieved from "http://grey.colorado.edu/emergent/index.php/Docs"
Personal tools