GNOME Goal: Port To New Documentation Infrastructure

Introduction

Altough some modules have been already ported, lots of GNOME modules still use gnome-doc-utils to generate its docs. This goal is to port to the new tools: yelp-tools

Guidelines

The port process is pretty easy, as an example take a look to this commit: http://git.gnome.org/browse/giggle/commit/?id=82d501477d5a327ba7ac77b6f8c64301b0177b07

Do not forget to update your autogen.sh if you are not using gnome-autogen.sh: http://git.gnome.org/browse/giggle/commit/?id=6a18ccb8aaa7aea472d3b01842bb23156c4e7a9e

Also, change the help targets in the app (ie, help: instead ghelp:): http://git.gnome.org/browse/giggle/commit/?id=ccd82daf7c0327dfa6a2bffe7b34caf1f08fd096

Instructions

The new build system is defined entirely by yelp.m4, which ships with yelp-tools. It uses itstool to manage translations and installs to the freedesktop.org help system. To use yelp.m4, you only need to initialize it in your configure.ac file, then set the correct variables in your help's Makefile.am. Since the new help system uses a different URI scheme to refer to help pages, you must also change any help targets in the code.

IMPORTANT: Do not port to the new system if the application still needs to run under GNOME 2. Yelp 2 does not recognize the new help system.

If you are already using gnome-doc-utils.make, you should first remove references to it:

If you have a custom autogen.sh that does not call gnome-autogen.sh, remove any references to gnome-doc-prepare.
In your configure.ac, remove any call to GNOME_DOC_INIT.
In your top-level Makefile.am, remove gnome-doc-utils.make from EXTRA_DIST.
In the Makefile.am for your help directory, remove the include line for gnome-doc-utils.make and the line "dist-hook: doc-dist-hook". You should also remove the DOC_ variables, but you will want to reference them when setting up the variables for yelp.m4.

To use yelp.m4:

Add YELP_HELP_INIT to your configure.ac file.
If you use a custom autogen.sh, you do not need to call a prepare script. However, it's useful to check for yelp-tools in autogen.sh to give a meaningful error message when people do not have yelp.m4. See http://git.gnome.org/browse/giggle/commit/?id=6a18ccb8aaa7aea472d3b01842bb23156c4e7a9e for an example.
Add @YELP_HELP_RULES@ to the top of your help's Makefile.am. The Makefile.am should be in the directory that contains the language directories. The language directories do not have individual Makefiles. All translations are managed by the Makefile.am for the document.
Set the following variables in the help Makefile.am:
- HELP_ID: The ID of the document, often the same as the name of the module or binary. This determines the directories under /usr/share/help where the files are installed. This will probably be the same as DOC_MODULE or DOC_ID.
- HELP_FILES: All Mallard page files, DocBook files, or XML files included with XInclude. Unlike gnome-doc-utils.make, you must also include the top-level DocBook file for DocBook documents (but see the note below).
- HELP_MEDIA: Any image, video, or other files that should be included, as paths relative to the C directory. This is just like DOC_FIGURES.
- HELP_EXTRA: Any extra files that also have to be included. This is the place to list XML files included with a SYSTEM directive.
- HELP_LINGUAS: The translations that will be built and installed. Do not include "C". This is the same as DOC_LINGUAS.

IMPORTANT: If this is for a DocBook document, the top-level DocBook file MUST be renamed to index.docbook. Do a "git mv" and include index.docbook in HELP_FILES.

You must change the help targets in any application that references this document. The old form is "ghelp:doc_id" for a document and "ghelp:doc_id?page_id" for a page in a document. The new form is "help:doc_id" for a document and "help:doc_id/page_id" for a page in a document. Do not forget to use a slash instead of a question mark to include a page ID. If you need to reference a section in a page in a Mallard document, use "help:doc_id/page_id#sect_id".

Comments

Status of this goal

$/!\$ Note: Updated automatical stats can be found at http://people.gnome.org/~fpeters/reports/new-documentation-infrastructure.html

Tip: If you choose to work on a module, create the bug report on the GNOME bugzilla for the relevant module, and make it block bug 681609. This way people will know someone already works on it, and won't duplicate the work you're doing.

State	Markup
todo	`<: #ff8080> todo`
patch	`<: #ffcc50> [[GnomeBug:xxxxx\|patch]]`
done	`<: #80ff80> [[GnomeBug:xxxxx\|done]]`
not needed	`<: #80ff80> not needed`

Above are the states and corresponding markup to update the modules state table below.

Tarball	Status
core
at-spi2-core	not needed
at-spi2-atk	not needed
dconf	not needed
evolution-data-server	not needed
glib-networking	not needed
gnome-bluetooth	done
gnome-online-accounts	not needed
gnome-control-center	not needed
gnome-desktop	done
gnome-icon-theme	not needed
gnome-icon-theme-extras	not needed
gnome-icon-theme-symbolic	not needed
gnome-keyring	not needed
gnome-menus	not needed
gnome-packagekit	done
gnome-power-manager	not needed
gnome-screensaver	not needed
gnome-session	not needed
gnome-settings-daemon	not needed
gnome-shell	not needed
gnome-themes-standard	not needed
gsettings-desktop-schemas	not needed
gvfs	not needed
mousetweaks	not needed
mutter	not needed
network-manager-applet	not needed
pulseaudio	not needed
telepathy-mission-control	not needed
core-utilities
baobab	not needed
brasero	done
empathy	not needed
eog	done
epiphany	not needed
evince	done
gcalctool	not needed
gnome-contacts	not needed
gnome-dictionary	done
gnome-disk-utility	not needed
gnome-font-viewer	not needed
gnome-screenshot	not needed
gnome-search-tool	done
gnome-system-log	done
gnome-system-monitor	done
gnome-terminal	done
gucharmap	done
nautilus	not needed
sushi	not needed
yelp	not needed
core-extras
gnome-backgrounds	not needed
gnome-user-share	done
vino	not needed
gnome-user-docs	done
core-fallback
GConf	not needed
gnome-panel	done
metacity	done
notification-daemon	not needed
core-os-services
accountservice	not needed
avahi	not needed
ConsoleKit	not needed
dbus	not needed
gdm	done
NetworkManager	not needed
PackageKit	not needed
polkit	not needed
upower	not needed
core-deps
atk	not needed
atkmm	not needed
cairo	not needed
cairomm	not needed
cantarell-fonts	not needed
caribou	not needed
clutter	not needed
clutter-gtk	not needed
clutter-gst	not needed
cogl	not needed
dbus-glib	not needed
dbus-python	not needed
desktop-file-utils	not needed
enchant	not needed
expat	not needed
farsight2	not needed
folks	not needed
fontconfig	not needed
gamin	not needed
gnome-js-common	not needed
gtksourceview	not needed
gdk-pixbuf	not needed
gjs	not needed
glib	not needed
glibmm	not needed
gmime	not needed
gnome-doc-utils	not needed
gnome-video-effects	not needed
gnutls	not needed
gobject-introspection	not needed
gst-plugins-base	not needed
gst-plugins-good	not needed
gst-plugins-farsight	not needed
gstreamer	not needed
gtk+	not needed
gtk-doc	done
gtkmm	not needed
gudev	not needed
hicolor-icon-theme	not needed
icon-naming-utils	not needed
iso-codes	not needed
itstool	not needed
intltool	not needed
java-gnome	not needed
js185	not needed
json-glib	not needed
libatasmart	not needed
libcanberra	not needed
libchamplain	not needed
libcroco	not needed
libdaemon	not needed
libdiscid	not needed
libgpg-error	not needed
libgcrypt	not needed
libgee	not needed
libgdata	not needed
libgnome-keyring	not needed
libgnomekbd	not needed
libgsf	not needed
libgtop	not needed
libgweather	not needed
libical	not needed
libmusicbrainz	not needed
libnice	not needed
libnotify	not needed
liboauth	not needed
libpeas	not needed
libproxy	not needed
librest	not needed
librsvg	not needed
libsigc++2	not needed
libsndfile	not needed
libsoup	not needed
libtasn1	not needed
libwnck	not needed
libxklavier	not needed
libxml2	not needed
libxslt	not needed
mm-common	not needed
nspr	not needed
nss	not needed
p11-kit	not needed
pango	not needed
pangomm	not needed
pixman	not needed
polkit-gnome	to do
poppler	not needed
py2cairo	not needed
pygobject	not needed
rarian	not needed
seed	not needed
shared-mime-info	not needed
sound-theme-freedesktop	not needed
speex	not needed
sqlite3	not needed
startup-notification	not needed
telepathy-glib	not needed
telepathy-logger	not needed
telepathy-farsight	not needed
totem-pl-parser	not needed
tracker	not needed
vala	not needed
vte	not needed
webkit	not needed
yelp-tools	not needed
yelp-xsl	not needed
zenity	done
libnl	not needed
lcms2	not needed
colord	not needed
apps
accerciser	done
aisleriot	done
anjuta	done
cheese	not needed
devhelp	not needed
evolution	done
file-roller	not needed
gedit	done
ghex	done
glabels	done
glade	done
gnome-color-manager	done
gnome-devel-docs	done
gnome-documents	not needed
gnome-games	done
gnome-nettool	done
nautilus-sendto	not needed
nemiver	done
orca	done
rygel	not needed
seahorse	done
totem	done
vinagre	done
Others
banshee	to do
gbrainy	patch
gnome-applets	done
gnome-media	done
gnote	done
gthumb	done
hitori	done
meld	done
nanny	to do
pitivi	done
planner	to do
rhythmbox	done
shotwell	patch
xchat-gnome	patch