Documentation

Andromeda Hackers Guide

Andromeda Documentation

If You Want To Download The Documentation

If you wish to download this documentation, including user comments, the simplest way is to use the "wget" command (or some Windows equivalent) and capture the entire contents of http://www.andromeda-project.org. This command will give you what you want:

$ cd /some/directory
$ wget -nH -r -k http://www.andromeda-project.org/

The switches used will have the following effects:

• The "-nH" option will put the docs directly into the directory you are sitting in. If you leave this out, wget will make a directory called www.andromeda-project.org and put the docs there.
• The "-r" option makes a recursive download.
• The "-k" option converts all of the links after download so that they point to the files on your local machine. This gives you complete off-line access to the docs.

You can repeat this command as often as desired to fetch a local copy of the latest documentation.

Features of the Documentation System

The Andromeda Documentation is managed by an Andromeda application named "adocs6". It allows us to mix ROBODOC style doc blocks in code with manually created pages. This program supports news a articles and user comments as well.

• Reading of ROBODOC style comment blocks from source code. The program that does this is robophp.php program, which duplicates the features of ROBODOC that we need and incorporates the other features listed here.
• Integration of manually created pages.
• Allow for moderated user comments.
• Automatically create Index and Table of Contents.
• Track file and line number of each ROBODOC block, produce a list of file.

Syntax Coloring

Sytax coloring is provided by Google's "code prettifer", available at http://code.google.com/p/google-code-prettify/. This is a javascript program that runs when the page is loaded. Code blocks are surrounded by PRE tags with classname "prettyprint". The YAML blocks also have the class "lang-ddyaml".

The available colors and their designations are:

• .str, color: #080, internal token PR_STRING
• .kwd, color: #008, internal token PR_KEYWORD
• .com, color: #800, internal token PR_COMMENT
• .typ, color: #606; internal token PR_TYPE
• .lit, color: #066; internal token PR_LITERAL
• .pun, color: #660; internal token PR_PUNCTUATION
• .pln, color: #000; internal token PR_PLAIN
• .tag, color: #008; internal token PR_TAG
• .atn, color: #606; internal token PR_ATTRIB_NAME
• .atv, color: #080; internal token PR_ATTRIB_VALUE
• .dec, color: #606; internal token PR_DECLARATION

For YAML, we match up the styles as follows:

• .kwd is used for top-level definitions.
• .atv is used for entity names and property values.
• .pun is used for nested definitions.

  ROBODOC-style Blocks

  The Andromeda documentation allows programmers to document functions, classes, properties and methods directly in code using specially formatted comment blocks. These blocks were originally written up for use with ROBODOC, but ROBODOC did not give us enough facility to integrate the results with other features, so the robophp.php program was written. This program implements the following ROBODOC features, anything not mentioned is not implemented.

  • The basic begin/end structure. A block begins with "/****X* Parent/Child", which is a comment begin "/*", followed by three more asterisks, followed by a type designator (explained below) another asterisk, and then the topic's parent, a slash, and the topic name. A topic ends with five asterisks on a line.
  • Inclusion of source code if desired.
  • Use of capitalized section names like "FUNCTION", "NAME" etc.
  • Use of indentation to indicate text that should be "PRE" formatted.
  • Use of asterisks to indicate UL lists.
  • Scanning of all topics for references to all other topics, replacing them with hyperlinks to the appropriate pages.
  • Trapping of blocks that have not end-block.

  In addition, we implement the following features:

  • Any PHP, HTML or JavaScript embedded in the block is escaped out for safe display.
  • Robophp.php allows for spaces in topic names.
  • Disambiguation pages for topics with the same name.

  To learn more about these features, examine the examples, or visit the RoOBODOC home page.

  ROBODOC uses a letter in the begin block to indicate what kind of block it is. We make use of the following values:

  • O - (Uppercase letter 'o') Javascript object
  • F - Javascript factory
  • f - functions
  • m - methods
  • P - class or object properties
  • c - class
  • M - module (a top-level entry in the table of contents
  • Y - Database definition (table, column etc)
  • Z - Database object property (description, type_id etc)

  General practice is to include the source of any routine that is less than 10 or 12 lines.

  For the NAME, we include the full object path where applicable, which serves to reinforce the object hierarchy. For example, the method "fireEvent" of the "x6events" object would have a name of "x6events.fireEvent".

  Because Andromeda contains both Javascript and PHP libraries, the first sentence of each topic usually begins by stating the relevant API and language of the topic, such as "The PHP method foo is used to..." or "The Javascript Object foo is used to..." or "The Javascript property foo.bar tracks..." or even "The database definition column defines a column for later placement in tables..."

  Wiki-style Features

  The documentation makes use of two wiki-style functions, which are image links [[image:imagename.png]] and direct page links as in [[A Page name]].

  Eventually the documentation will automatically seek strings which match page names and substitute in links, but until this is available page links will be necessary.

  Image links will always be used, there are no plans to replace them with any other format or automated function.

  Andromeda Hackers GuideBuilding Our Debian Package

  User Comments

  There are no user comments yet on this page.

  ---

  Add A Comment

  Comments will not appear until after they are moderated. Comments are usually moderated within a few hours on weekdays, but may take longer on weekends and holidays.
  
  

  Name or nickname: (This will appear with your comment)

  
  
  

  Email (this will never be displayed)

  
  
  

  Enter your comment here. Use [b] and [/b] for bold, [i] and [/i] for italic, and [pre] and [/pre] for code samples. All literal HTML and PHP that you enter will be escaped out and displayed as you enter it.