Difference between revisions of "Gnome Doc Utils"
From GnuCash
(Note about successor "Yelp Tools") |
m (xml2po: both it parts) |
||
| (7 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
| − | An | + | 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? | ||
| − | + | # 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> | ||
| − | ; | + | ;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.
Contents
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-utilsone 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/xsltxslts 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-utilsa 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?
- 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
- add 'GNOME_DOC_INIT' to configure.ac
- Does it require a more complex construction?
- Is a special place before or after something else required?
- ./autogen.sh # will call aclocal and insert /usr/share/aclocal/gnome-doc-utils.m4 in aclocal.m4
- [[md build;] cd build;.]./configue <your options>
- Notes
- There is a help file for gnome-doc-make.
- Standard OMF Elements
- Scrollkeeper's omf extensions
