Difference between revisions of "Gnome Doc Utils"

Revision as of 06:26, 8 September 2019

An ancestor of the GNOME Documentation Build Utilities (GDU) Gnome Documentation Project's (GDP) Document Templates have been the base of the Gnucash Documentation. At some point this relation was forgotten and no further updates found their way in our docs. Most parts of the build system are based on scrollkeeper_example2 (manual).

In theory we depend already on GDU as xml2po, which is used in guide/it, is part of it.

This page will contain notes while updating.

Gnome 1: GDP Templates

For the beginning see commit f2f6d68: commit changes to move to gdp stylesheets, generate html files in subdir of docs folder, add HACKING, requirements, initial guide dir setup

A copy of the manual, which is no longer available at gnome.org, can be found at http://www.inkstain.net/fleck/handbook/.

Overview

In GNOME3 the Gnome Doc Utils are replaced by Yelp Tools, which might be nice for Mallard files, but have now in 2017 only partial support of DocBook source files. So we can not use them.

For technical details the README on GitHUb might be a starting point.

Distributions might split the GDU in a runtime, a devel and several language packages:

Runtime Package

Beneath the program

> gnome-doc-tool --help
Usage: gnome-doc-tool <COMMAND> [OPTIONS] FILES...
Process a documentation file.

COMMAND is one of:
  list-icons   list automatic icons and watermarks
  list-media   list all referenced media files
  html         convert the documents to HTML
  xhtml        convert the documents to XHTML
  css          create a CSS file for a Mallard document
  help         display this help and exit

it contains

• in /usr/share/gnome-doc-utils one template each for an app and an applet,

a bunch of icons: admon-{bug|caution|important|note|tip|warning}.{png|svg}

and watermarks: watermark-{blockquote-{00AB|00BB|201C|201D|201E}|code[-python]}.png

• in /usr/share/gnome/help/gnome-doc-{make|xslt} help files
• in /usr/share/xml/gnome/xslt xslts for docbook (gnome2) and mallard (gnome3) sources:

common: {theme|utils}.xslt

docbook:

common: db-{chunk|common|label|title|xref}.xslt

html: db2{html{-{autotoc|bibliography|block|callout|classsynopsis|css|division|ebnf|footnote|funcsynopsis

|index|info|inline|l10n|list|media|quanda|refentry|suppressed|table|title|xref}|}xhtml}.xslt

omf: db2omf.xslt

utils:{chunks|credits|figures|graphics|ids}.xslt

Devel Package

Beneath the program

> gnome-doc-prepare --help
Usage: gnome-doc-prepare [OPTION]...

Prepare a package to use gnome-doc-utils.

    --automake        work silently, and assume that Automake is in use
-c, --copy            copy files rather than symlinking them
    --new-document DOCUMENT
                      initialize help/DOCUMENT/*
    --debug           enable verbose shell tracing
-n, --dry-run         print commands rather than running them
-f, --force           replace existing files
    --help            display this message and exit
    --version         print version information and exit

You must 'cd' to the top directory of your package before you run
'gnome-doc-prepare'.

• an /usr/share/aclocal/gnome-doc-utils.m4
• /usr/share/gnome-doc-utils/gnome-doc-utils.make, which can be linked or copied
• in /usr/share/gnome-doc-utils a bunch of templates for document.xml, omf-in, make, legal-xml.

Plan

Merge the templates in our files.

Progress

Preparation

• The --copy option should avoid the dependency?

1. gnome-doc-prepare

 > gnome-doc-prepare -c
 Remember to add 'GNOME_DOC_INIT' to configure.ac.
 You should update your 'aclocal.m4' by running aclocal.
 rm -f gnome-doc-utils.make
 cp -f /usr/share/gnome-doc-utils/gnome-doc-utils.make gnome-doc-utils.make

• with --new-document docname it will create help/docname/{C/docname.xml|docname.omf.in|makefile.am}

  It will need some tweaks to apply it on guide/gnucash-guide

1. add 'GNOME_DOC_INIT' to configure.ac

   • Does it require a more complex construction?
   • Is a special place before or after something else required?

2. ./autogen.sh # will call aclocal and insert /usr/share/aclocal/gnome-doc-utils.m4 in aclocal.m4
3. [[md build;] cd build;.]./configue <your options>

Notes

There is a help file for gnome-doc-make.

Standard OMF Elements

Scrollkeeper's omf extensions