User Documentation

The main MakeHuman user document is the  Users Guide so anything that affects the way the user interacts with MakeHuman needs to be fed back into that document. The Quick Start document contains a very much cut-down version of the Users Guide, but it should be checked whenever the Users Guide is updated.

Once a version of MakeHuman has been formally released a separate copy of these documents, covering that release, will need to be published and formally managed. That documentation can subsequently be updated with corrections, but information relating to further application enhancements will need to be incorporated into the draft documents for the next release.

Registered members of the MakeHuman Wiki can directly update the drafts of these documents for future releases or can pass texts and graphics to the translation and editorial team for incorporation into the documents.

Writing Style for the Quick Start

The Quick Start guide should be kept as short as possible. It is maintained in a single Wiki page to enable users to easily read and print the entire document. The target is to keep this document to about 5 pages when printed. Where links are incorporated into the document the fully qualified URL should be written out in the text so that the URL can be read correctly in the printed version. The purpose of this document is to provide an easy to read entry point into the MakeHuman application whether or not the user's first language is English.

Text needs to be as short and clear as possible. Well structured graphics help new users a lot when learning an unfamiliar GUI. Poor graphics can confuse the hell out of them. Care needs to be taken to maintain this document to a high standard so that the text and the graphics are correct and correspond with each other and the version of MakeHuman to which the document applies. If you spot errors in this document then please take the time to correct it or report your findings through the discussion thread for that page, or by emailing the Wiki Administrators.

Writing Style for the Users Guide

The Users Guide is not intended to be read from start to finish, but rather to be dipped into as required when the user attempts to do something they may not have done before, or that they've just forgotten how to do. The main section headings are intended to closely match the names and the sequence of the main section headings in the Quick Start document so that users who have read the Quick Start will be able to easily locate the corresponding detail in the Users Guide.

Each section is in it's own Wiki page and should cover the topic in more detail than the equivalent section in the Quick Start document. The section heading should appear as a level 1 header at the top of the section. Links to the previous section and the next section should appear at the foot of the page. Level 2 and Level 3 headings can be used within the body of the page. Consistency across sections is important as the Wiki content will be used to generate alternative consolidated document formats suitable for downloading or printing.

---

Developer Documentation

The main MakeHuman developer document is this Developers Guide . Anything you do that affects the way the MakeHuman development or build processes are performed needs to be fed back into that document. This document also contains reference information of value to other developers including developers outside the core development team such as Plugin developers. It is therefore important to feed back changes to that reference information so that it is incorporated into the Developers Guide.

There should only ever be one master copy of the Developers Guide on the Wiki. It is a living document that evolves in real-time as the processes and procedures change. Registered members of the MakeHuman Wiki can directly update this document or can pass texts and graphics to the translation and editorial team for incorporation into the documents. Care needs to be taken to make sure this document is always maintained in a cohesive and clear state. Before making changes to this document it's best practice to get the text checked to make sure that someone else can understand it. Also spend a few seconds thinking about and checking which other sections of the document may need to also be updated. The Wiki provides a 'Backlinks' button that lists which other pages refer to the page you're editing. It's worth checking that list to see if it reminds you of other pages that may need updating.

Provision of incorrect or inconsistent information in the Developer Guide can waste a lot of developer time that could be better invested in the development of new features.

Writing Style for this Developers Guide

As has been mentioned, this is a living document which could be subject to frequent change and is therefore most likely to be used online rather than downloaded or printed. Sections can be added or reorganised as required by the development team. Although clarity is important it is more important that information of relevance to other developers is up to date and complete rather than necessarily being in perfect English. Developers should therefore update this document as information becomes available. New or updated content can be refined and tidied up as resource becomes available to do that.

The section heading should appear as a level 1 header at the top of the section. Links to the previous section and the next section should appear at the foot of the page. Level 2 and Level 3 headings can be used within the body of the page. Some sections of this document contain their own table of contents (such as this one). This is not a requirement, but just makes sense with certain sections where the reader is likely to wish to go directly to a sub-section. If a table of contents is included there should be a Horizontal Rule drawn between each level 2 header and a link back to the table of contents at the foot of each sub-section. Consistency of style across sections is not vital, but some investment in making a page easy to read is worthwhile and can easily save more developer time than it costs.

---

Code Documentation

Full Application Programming Interface (API)

A small central core of the MakeHuman application has been written in 'C', but most of the functional behaviour is implemented using Python which provides an Application Programming Interface for the development of plugins and helper applications. Both the 'C' functions and the Python methods, classes and functions are documented using markup contained in the source code and generated into online HTML documents. MakeHuman developers and plugin developers may also need to understand how the humanoid model is constructed so this page also provides URLs to access model documentation.

It is recommended that you read the Application Overview section of this document to gain familiarity with how the application works before diving into the detailed API documentation.

Documenting C code

We use Doxygen (see http://www.stack.nl/~dimitri/doxygen/index.html) to document C code. This utility searches for specialy formatted comments within the code which it uses in conjunction with documentation elements that it generates automatically. The download provides a wizard to install the application. To set up the Doxygen application you should specify your local SVN MakeHuman project directory as the input directory, specifying a recursive search for only '.c' and '.h' files. Doxygen is available with a GUI interface. Whenever you change a C source file you should ideally run Doxygen to make sure that your changes don't break the documentation utility.

Comment fields need to be maintained by developers within the source code so that the API documentation can be automatically generated. These comments need to describe the proper use of each module and function. If you make changes affecting the function or the use of the application code you will need to update the comment fields and test those changes to make sure you don't break the documentation utilities before you submit your updated code to the SVN repository.

To validate and generate 'C' API documentation you will need to:

• Download and install Doxygen (see http://www.stack.nl/~dimitri/doxygen/index.html). The installation executable installs a GUI application.
• Set up a project to parse the 'src' directory containing 'C' code and the 'include' directory containing the 'C' header files. The project should be configured to generate HTML documentation.
• 
  

Documenting python code

We use epydoc (see http://epydoc.sourceforge.net/) and restructured text markup from the docstrings module (see http://docutils.sourceforge.net/docs/user/rst/quickref.html) to document Python code.  Descriptive text needs to be incorporated into each Python file describing the purpose of the module and the operation of each function (with a description for each of its parameters). This text is picked up from SVN by an automatic documentation utility and automatically  built everyday into structured API documentation in the form of web pages here: http://mh.jwp.se/apidocs/

Information destined for the API documentation needs to be encoded within Python comment blocks. You should incorporate blocks of using restructured text comments at the top of each Python module to describe the module, and at the top of each method to describe the method and its parameters using one of the existing modules as an example. There is a test site where you can try out individual blocks of the 'restructured text' markup language online at http://www.hosting4u.cz/jbar/rest/rest.html . The MakeHuman project has adopted a very straight-forward and standardized format for these comment blocks. You can see an example of this in the http://code.google.com/p/makehuman/source/browse/trunk/makehuman/mh_core/algos3d.py Python file.

If you want to generate the API documentation on your local machine, you will need to run the epydoc application which is available with both a command-line interface and a GUI interface. Whenever you change the documentation comments within a Python source file you should run epydoc to make sure that your changes don't break the documentation utility.

---

Mesh Face Group Documentation

We use POV-Ray (see http://www.povray.org/) to render images of each of the face groups used by the MakeHuman application (see http://makehuman.sourceforge.net/FaceGroups/index.html). These are displayed using a small number of short, hand-crafted HTML pages. MakeHuman face groups should theoretically be quite stable, so the documentation should not need to be regenerated very often, but if changes are made, it is relatively straightforward to regenerate the images.

The following pages contain images showing all of the facegroups that go to make up the MakeHuman base humanoid model:

Flat HTML	Head	Neck	Body	Hands	Arms	Feet	Legs	Teeth	Joints
JavaScript Browser	Head Browser	Neck Browser	Body Browser	Hands Browser	Arms Browser	Feet Browser	Legs Browser

The 'JavaScript Browser' pages allow you to select two images from the full set to compare side-by-side.

POV-Ray is a free raytracing software available for most platforms that normally takes just a few minutes to download and install. To regenerate images you'll need to know how to get the software to render a scene file using command-line animation options. The '\data\povray\' directory on SVN contains a special POV-Ray scene file called 'makehuman_facegroup_documentation.pov' and a special POV-Ray include file called 'makehuman_groupings.inc'.

Image Regeneration

The scene file 'makehuman_facegroup_documentation.pov' uses the POV-Ray animation feature to cycle through the hundreds of face groups, highlighting each individual face group in turn. It adds text to the image describing the face group being rendered and incorporates a few 'special' images, such as an annotated diagram of each set of teeth and an illustration of the joint positions. The scene file starts with a block of comments that describe how to use the file and which command-line options to use to regenerate individual images or sequences of images. The mechanism for entering command-line options is Operating System dependant. The Windows version provides a little text box at the top-left of the edit screen for command-line options. Each image takes between half a minute and a minute to render on a reasonably fast machine. The entire set can be regenerated (unattended) in about 5 hours and will initially occupy about 70MB.

Images can be generated directly in JPEG format by specifying the command-line option '+fJ', but are not highly compressed. The generated images therefore need to be compressed further before being loaded onto the web site (see below).

Configuration Changes

The POV-Ray include file 'makehuman_groupings.inc' contains definitions for high level groupings. For example, an array called 'MakeHuman_LeftFingerGroup' is declared that contains 15 face groups, including "l-hand-finger-1-3" which is the face group containing the tip of the thumb on the left hand. 'MakeHuman_LeftFingerGroup' is subsequently incorporated into the 'MakeHuman_LeftHandGroup' array and so on. If a face group name has changed you simply update the name in this file.

If you add a face group to, or delete a face group from an array you will need to adjust the dimension of that array. You will also need to adjust corresponding image number settings in the scene file 'makehuman_facegroup_documentation.pov''. Image numbers are grouped as listed at the top of the scene file, leaving gaps to accommodate changes. For example, if you need to add one face group to the head you'll need to adjust the range of numbers from '100 to 179' to '100 to 180'. The next grouping doesn't start till 190, so this doesn't cause a conflict. Next you'll need to locate the section in the scene file that generates the images for face groups on the head and change the '#if' statement so that it generates the correct number of images. So, find the line that says '#if (Image_Number>=100 & Image_Number<=179)' and adjust it to read '#if (Image_Number>=100 & Image_Number<=180)', then adjust the comments for that section of code.

Certain sections are a little more complicated because they generate pairs of sets of images. For example, there is a single block of code to handle both the left foot and the right foot. In this case you'll need to adjust both of the adjacent blocks of numbers. In addition there is a little bit of code within the main '#if' clause that determines which foot to generate for a particular range of image numbers. In the following example you can see that the first block generates the left foot and the second generates the right foot. If two face groups have been added to each foot then you would need to adjust this '#if' statement to say '#if (frame_number<=222)' telling it to treat everything from 200 to 222 as the left foot. You would also need to adjust the right foot parameter from 221 to 223, so that the code picks up the correct elements from the right foot array.

  #include "makehuman_groupings.inc"
  #if (frame_number<=220)
    #declare MakeHuman_SelectedGroups = MakeHuman_LeftFootGroup;
    #local ThisObject = object {ShowElement (MakeHuman_SelectedGroups,"Left Foot" ,200)}
    #local Orientation = 1;
  #else
    #declare MakeHuman_SelectedGroups = MakeHuman_RightFootGroup;
    #local ThisObject = object {ShowElement (MakeHuman_SelectedGroups,"Right Foot",221)}
    #local Orientation = -1;
  #end

The web pages used to display these images are hand-coded to display the correct images, so any numbering changes also need to be reflected in the HTML files used to draw those web pages (see below).

Compression

The online documentation uses JPEG images with quite a high rate of compression. POV-Ray's command-line option '+fJ' can be used to generate JPEGs directly, but they are not very highly compressed. The free IrfanView software can be used to further compress the files in batch mode, which takes just a few seconds to compress hundreds of files. A quality setting of 70% is fine and reduces file sizes to about 15% of the size generated by POV-Ray, reducing the disk space required from 70MB to about 10MB.

Web Page Updates

Each group of images is displayed in two web pages. One provides a simple view of all of the images in that group without using any JavaScript. This ensures that people can display the images without JavaScript enabled and without getting any irritating messages. The second page displays rows of tiny thumbnails along the top, with two full-sized images that change as the user rolls the mouse over, or clicks a thumbnail. The HTML files contain lists of numbered images that need to be updated if the numbering sequence changes. This can be performed using any available text editor.

Updating the Online Copy

An administrator with appropriate authorisation will need to load an updated copy of the face group documentation on the SourceForge Web Project at http://makehuman.sourceforge.net/FaceGroups/ . This can be most easily done using drag and drop with a WinSCP client.