This is a collection of various articles describing the Documentation Project at Blender3d. Some of the articles may be useful to people wishing to contribute to the Project, by giving an overview on the procedure of obtaining Source Documentation, editing, and submitting back to DocBoard.

The Documentation Project is a work-in-progress, community undertaking devoted in an effort to create an up-to-date Blender manual. The Project will also aid in full internationalization support to make Blender more accessible worldwide.

 

The DocBoard maintains a repository containing the Documentation, this repository can be accessed via CVS. The Concurrent Versioning System or CVS allows many people to simultaneously work on data, while preserving any changes made to the data. This permits modifications without permanently breaking the code. CVS also has the ability to log who, when and why changes were made to the source data.

 

Documentation source is in the form of XML. XML is analogous to HTML, basically they are both text languages organizing data. XML provides flexibility, can be read by both human and computer, but most importantly, XML gives data structure. The reason for using XML is once we have defined the structure, we gain the ability to use and output the data to a variety of formats. The Project also contains numerous PNG format image files displaying the various Blender3D windows and buttons.

 

Structuring the source data is assisted through the use of DTD. This tells the document structure to behave in a certain manor. Consider the DTD to be a template for the data. A popular DTD is DocBook, a template that gives data the structure of a book and is used extensively in Documentation Projects. By using DocBook DTD and XML we give our data strict rules to adhere by. An example would be a book chapter must come below a book title. We can also use this to output different fonts in the title than the font used in the chapter or body.

 

The output of our source can be made more attractive by using CSS or Cascading Style Sheet. CSS allows you to attach styles to structured documents. It's a language to describe style. The main advantage is that XML tags are hidden allowing for a much cleaner presentation of data, also each style sheet you define can be reused for all pages of the Documentation.

Source for the Blender3D Documentation Project is available for download via CVS. It is this repository that is maintained by the DocBoard and accessed by contributors and editors.

 

The easiest method in using CVS, is a graphical interface CVS client. This appears as a nice windowed program with features and commands available in drop down menus. Some examples of CVS clients would be: WinCVS www.wincvs.org and MacCVSClient www.heilancoo.net/MacCVSClient/ They are available for Windows, Mac, and Linux.

 

CVS can also be used on the command line. You will need to download and build the CVS executable if you don?t already have it installed. CVS can be found here, www.cvshome.org Most *nix environments should have cvs installed by default. Entering the command %cvs in the terminal should show you if its installed or not.

 

Connecting to the Blender3D CVS server is accomplished by using the following settings and if using a GUI CVS to access the Documentation Project, add the following in your applications preferences:

After entering this information you will want to Check Out the source Documentation. The correct module name is: BlenderManual2.32. CVS will then download the Documentation to the Folder you specified.

If using the command line CVS to access the Documentation Project, type the following from you terminal:

When prompted for a password for anonymous, simply press the Enter key.

Once you have begun the Check Out process you will see the source files that make up the Documentation Project being printed in the Console or Terminal. These are the XML, DTD and image files used in the Blender3D manual. After downloading from CVS is complete you can begin to edit the files with your favorite XML editor.

Now that you have the source Documentation downloaded to your machine it is time to open the XML files and start editing them. Because XML is human readable and very similar to HTML it is possible to use your favorite text editor. This may include NotePad, TextEdit, MS Word, etc. Also you can use your favorite *nix terminal text editor such as vim, pico or emacs, in fact emacs has a special XML editing module available as a plug-in.

 

There are several GUI XML editors that allow the loading of DTD and CSS. These editors allow, what you see is what you get, approach to editing the source Documentation. This is helpful in seeing how the final output will look, because XML tags can be hidden or viewed in multiple other ways. It also allows the adding of XML tags from menus which can be a big help for the beginner. Many of the available open source editors run on Java, and are multi-platform. An example would be Xerlin www.xerlin.org. A large list of other XML editors can be found here, www.xmlsoftware.com/editors.html.

 

I have become partial to the XML editors available from www.morphon.com and www.xmlmind.com/xmleditor/ They come included with the DocBook DTD and CSS as well as a CSS editor. The programs come with everything you need to get started out of the box. It will not open the whole Blender3d manual at the time of this writing, but they will open individual chapters. I expect this to change after the whole Documentation Project is placed into the CVS repository. These XML editors were recommended to me by the leader of a similar Documentation Project. I pass this recommendation on to you. These two XML editors and the CVS client mentioned earlier are the only pieces of software you need to get started working on Blender3d Documentation.

 

There are several packages designed for working on DocBook Projects that may complement you suite of tools, or are necessary if going the *nix terminal route. The DocBook DTD should be obtained. You can obtain the DocBook DTD in the downloaded source from the Blender3d CVS, included with your XML editor, or from the the DocBook web site www.docbook.org Again this tells your XML Document to behave like a book. DocBook Utils is a collection of executables made for exporting DocBook XML files into html, and pdf, among others formats. DocBook Utils is not needed for this Project but it may come in handy for your own experimentation. You can find the DocBook Utilities here www.freshmeat.net/projects/docbook-utils Also not necessary, but helpful, is a collection of style sheets for DocBook. These are rules of style, they give your Documentation a specific look. An example is the Font size of a Chapter is to be larger than the Font used in a Paragraph. Many of the XML editors use these style sheets to present the data to you in a nice look and feel while you worry more about the content than the underlying XML tags. Style sheets come in the form of CSS, XSLT, and DSSSL. You can obtain style sheets created by Norman Walsh, an author using DocBook. He has generously supplied his vision of what a good piece of Documentation should look like and you can download it here www.freshmeat.net/projects/docbook-utils. Finally you should look into the TeX typsetting environment. It is a tool used for documenting mathematic formula, manuals, and other technical documents. TeX has the ability to export to numerous formats such as HTML and PDF. You can find TeX here www.tug.org/teTeX/.

 

Screen shots of the various Blender3D windows and menu buttons also need to be kept up to date. It is recommended that you maximize the Blender3D window. This can be done on the command line %./blender -p 1 1 1280 1024 or by clicking on the maximize button on the title bar. You should have the default .B.blend file and default theme to avoid confusion and to ensure consistency. Blender provides the built-in ability to take screen shots of the 3D window and menus. Use CTRL-F3 to take a window screen shot, and SHIFT-CTRL-F3 to take a full screen shot. It may be necessary to use an external application to do this. Your OS should have some mechanism to take screen shots, and if not, Gimp the Gnu Image Manipulation Program, has this feature. Gimp can also be used for adding highlights and notes to the images, these should be pure yellow (#FFFF00). Make sure you save the images in PNG format. Please get Gimp from www.gimp.org

Now that you have made the appropriate edits to the Blender3d Documentation, you will need to mirror these changes on the CVS repository. The Blender3d DocBoard oversees all changes to the source Documentation, and it is through them, changes can be realized. The DocBoard excepts several forms of upload.

 

The DocBoard will except the edited XML files and edited PNG graphics as attachments to e-mail. Again the e-mail address is bf-docboard@blender.org and to be added to the list projects.blender.org/mailman/listinfo/bf-docboard

You could also send Diff output to DocBoard. Diff finds differences between two files. Diff should be on most *nix type systems. CVS should also have the ability to generate Diff output. Copy and paste this output to your e-mail. The DocBoard will then use this information to patch the source Documentation with the utility, Patch.

 

CVS also has the ability to upload to the Blender3d Documentation server. You will however need to be granted permission to use this method. The process is similar to checking out the source Documentation. If your using the GUI CVS you should see a drop down menu option named commit. If your using the command line CVS you will need to type %cvs commit from within the working directory. If you feel you will be doing lots of editing or contribution to the Blender3D Documentation Project than you should please ask for CVS permissions on the mailing list projects.blender.org/mailman/listinfo/bf-docboard

It is often helpful to see what the final version of the XML files will look like. Not only is the text easier to read without all the XML tags but it is also what the end user will be viewing. To ensure that this will be a favorable experience for the user its a good idea to generate HTML and PDF files from the XML Documentation.

 

The XML editors that I recommended have the ability to output to HTML either in chunk or table of contents form. A myriad of converters are available to generate HTML and PDF from XML. Some of these being the before mentioned DocBook Utils as well as the TeX typesetting environment.

 

It is difficult to recommend the best one, or workflow, but what does work well for me is to output a chapter of XML source and PNG images to chunk HTML and to then convert that to PDF and joining multiple PDF if necessary. However you may be accustomed to a certain workflow, whatever works best for you here.

 

Most importantly is that XML Source Documentation be current to the Blender3D version available, that it is valid XML with up-to-date images, and with consistent, typo free texts. Thank-You.