WineHQ
WineHQ

Chapter 6. Documenting Wine

This chapter describes how you can help improve Wine documentation.

Like most large scale volunteer projects, Wine is strongest in areas that are rewarding for its volunteers to work in. The majority of contributors send code patches either fixing bugs, adding new functionality or otherwise improving the software components of the distribution. A lesser number contribute in other ways, such as reporting bugs and regressions, creating tests, providing organizational assistance, or helping to document Wine.

Documentation is important for many reasons, and is often the key to the end user having a successful experience in installing, setting up and using software. Because Wine is a complicated, evolving entity, providing quality up to date documentation is vital to encourage more people to persevere with using and contributing to the project. The following sections describe in detail how to go about adding to or updating Wine existing documentation.

6.1. An Overview Of Wine Documentation

The Wine source code tree comes with a large amount of documentation in the documentation/ subdirectory. This used to be a collection of text files culled from various places such as the Wine Weekly News and the wine-devel mailing list, but was reorganized some time ago into a number of books, each of which is marked up using SGML. You are reading one of these books (the Wine Developer's Guide) right now.

Since being reorganized, the books have been updated and extended regularly. In their current state they provide a good framework which over time can be expanded and kept up to date. This means that most of the time when further documentation is added, it is a simple matter of updating the content of an already existing file. The books available at the time of writing are:

  • The Wine User Guide. This book contains information for end users on installing, configuring and running Wine.

  • The Wine Developer's Guide. This book contains information and guidelines for developers and contributors to the Wine project.

  • The Winelib User's Guide. This book contains information for developers using Winelib to port Win32 applications to Unix.

To obtain a copy of the Wine documentation refer to the Documentation Git tree.

Another source of documentation is the Wine API Guide. This is generated information taken from special comments placed in the Wine source code. When you update or add new API calls to Wine you should consider documenting them so that developers can determine what the API does and how it should be used.

The next sections describe how to create Wine API documentation and how to work with SGML so you can add to the existing books.