Documentation:Main

From GIMP Developer Wiki
Jump to: navigation, search

GIMP User Manual

These pages are for coordinating the documentation effort for the user manual.

Roadmap

Release 3.0

    • Can we move to pandoc to write the source content in Markdown, ASCII Doc or similar? From there generate DocBook XML and go with publican ...
  • Include/maintain the tutorials from www.gimp.org. How do we sync it in gimp-web?

Release 3.2

  • Check if we can integrate the manual with the GNOME help browser. I think the possibility was always there, but simply lacked on man power.
  • Proposal: Synchronize with GIMPs branching model and release dates. Use feature branches for features of the next GIMP release. If we decide to have release dates separately from GIMP, then a bugfix branch for changes, that result from GIMP bugfixes in the next GIMP release, would be necessary.
  • Split the current reference from the manual (tutorials etc). That means we provide a reference and a tutorial section and maintain them. We'll have to decide which one will be shipped with GIMP. The manual, reference, both?

Release 3.4

  • Incorporate the quickreference with the manual better: There must be the way we could generate the quick reference out of the manual or perhaps even GIMP, so that we store/retrieve shortcuts from a single source.
  • Leverage GUI testing tools to automate the process of making screenshots from all GIMP dialogs/menus etc.

Future

  • Provide a better way to interact with the GIMP help browser. We could document special URLs which allow the user to open certain dialogs in GIMP (security!) or show them how to access dialogs.
  • Add a search engine to search fastly in the docs and optionally additional websites (www.gimp.org, forums, social network topic groups, mailing lists etc). For instance see the Eclipse help as inspiration. https://bugzilla.gnome.org/show_bug.cgi?id=152987
  • Automatically generate translation statistics for every chapter of the documentation to guide interested contributors to spots that need some love.
  • Provide additional formats for e-readers, e.g. epub. Epub is almost HTML with a bit of metadata sprinkled inside it. Kindle Mobi is similar.

History

Technical Background

The GIMP help browser uses a mapping between GIMP widgets and the generated HTML files. The id in the help has to match the id used by the widget.

Basis of the manual is DocBook XML. Translations are provided using gettext. All translations are stored in their respective po files in the po/ISO_CODE directory. When HTML is build, new DocBook XML is generated for the specific language based on the translation. Based on the newly generated XML, the HTML is generated.

In case the project changes to a new documentation system, the following requirements must be met:

  • stable ids for documents
  • unique ids for documents
  • versioning
  • freezing of documents to a certain version, eg. to say this document is valid for GIMP 2.6

Initial Goals

Our initial goals set in 2003 were to provide a useful manual for GIMP > 2. This has been reached. Over time we felt that we can provide additional formats for print out, but never went beyond a stable state.

Initial Problems

We've had a very low amount of contributions in the early stages of the project, since all translation had to be done in the XML. Since we've moved to gettext, it helped us to keep translation contributions.


Current

Even though there is a lack of maintainership towards releases, contributions are still happen at a high rate. Releases need to be made more frequently and the current work in progress on http://docs.gimp.org is not frequently updated.