Difference between revisions of "Gnome Doc Utils"

From GnuCash
Jump to: navigation, search
(Note about successor "Yelp Tools")
m (xml2po: both it parts)
 
(7 intermediate revisions by 2 users not shown)
Line 1: Line 1:
An early form of the [https://developer.gnome.org/gnome-doc-make/unstable/intro.html.en GNOME Documentation Build Utilities] ('''GDU''') seem to 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.
+
An ancestor of the [https://developer.gnome.org/gnome-doc-make/unstable/intro.html.en 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 ([http://scrollkeeper.sourceforge.net/documentation/scrollkeeper_example2_manual/index.html manual]).
 +
 
 +
In theory we depend already on GDU as xml2po, which is used in the italian document parts, is part of it.
  
 
This page will contain notes while updating.
 
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==
 
==Overview==
 
In GNOME3 the ''Gnome Doc Utils'' are replaced by [https://wiki.gnome.org/Apps/Yelp/Tools 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.
 
In GNOME3 the ''Gnome Doc Utils'' are replaced by [https://wiki.gnome.org/Apps/Yelp/Tools 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 [https://github.com/GNOME/gnome-doc-utils/README README on GitHUb] might be a starting point.
+
For technical details the [https://github.com/GNOME/gnome-doc-utils/blob/master/README README on GitHUb] might be a starting point.
  
 
Distributions might split the GDU in a runtime, a devel and several language packages:
 
Distributions might split the GDU in a runtime, a devel and several language packages:
Line 23: Line 30:
 
   help        display this help and exit
 
   help        display this help and exit
 
it contains  
 
it contains  
* in <code>/usr/share/gnome-doc-utils</code> a bunch of icons and watermarks
+
* in <code>/usr/share/gnome-doc-utils</code> 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 <code>/usr/share/gnome/help/gnome-doc-{make|xslt}</code> help files
 
* in <code>/usr/share/gnome/help/gnome-doc-{make|xslt}</code> help files
* in <code>/usr/share/xml/gnome/xslt</code> xslts for docbook (gnome2) and mallard (gnome3) sources.
+
* in <code>/usr/share/xml/gnome/xslt</code> 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===
 
===Devel Package===
Line 55: Line 71:
 
===Preparation===
 
===Preparation===
 
* The --copy option should avoid the dependency?
 
* The --copy option should avoid the dependency?
* Not shure, if --new-document gnucash-help is required and how to apply it on guide/gnucash-guide
+
# gnome-doc-prepare  
# gnome-doc-prepare
 
 
<pre> > gnome-doc-prepare -c
 
<pre> > gnome-doc-prepare -c
 
  Remember to add 'GNOME_DOC_INIT' to configure.ac.
 
  Remember to add 'GNOME_DOC_INIT' to configure.ac.
Line 62: Line 77:
 
  rm -f gnome-doc-utils.make
 
  rm -f gnome-doc-utils.make
 
  cp -f /usr/share/gnome-doc-utils/gnome-doc-utils.make gnome-doc-utils.make</pre>
 
  cp -f /usr/share/gnome-doc-utils/gnome-doc-utils.make gnome-doc-utils.make</pre>
 +
* with --new-document docname it will create <tt>help/docname/{C/docname.xml|docname.omf.in|makefile.am}</tt>
 +
*: It will need some tweaks to apply it on guide/gnucash-guide
 
# add 'GNOME_DOC_INIT' to configure.ac  
 
# add 'GNOME_DOC_INIT' to configure.ac  
 
#:* Does it require a more complex construction?
 
#:* Does it require a more complex construction?
 
#:* Is a special place before or after something else required?
 
#:* Is a special place before or after something else required?
# ./autogen.sh # will call aclocal
+
# ./autogen.sh # will call aclocal and insert /usr/share/aclocal/gnome-doc-utils.m4 in aclocal.m4
 
# [[md build;] cd build;.]./configue <your options>
 
# [[md build;] cd build;.]./configue <your options>
;Note: There is a help file for gnome-doc-make.
+
;Notes: There is a help file for gnome-doc-make.
 +
:[http://www.ibiblio.org/osrt/omf/omf_elements Standard OMF Elements]
 +
:[http://scrollkeeper.sourceforge.net/documentation/writing_scrollkeeper_omf_files/ar01s04.html Scrollkeeper's omf extensions]

Latest revision as of 06:28, 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 the italian document parts, 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