Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/kj-sh604/gnome-doc-utils

copy of https://gitlab.gnome.org/Archive/gnome-doc-utils#commit=c03cc0963996934e03587af3e351c2bb9dab6b2a for agave PKGBUILD
https://github.com/kj-sh604/gnome-doc-utils

Last synced: about 1 month ago
JSON representation

copy of https://gitlab.gnome.org/Archive/gnome-doc-utils#commit=c03cc0963996934e03587af3e351c2bb9dab6b2a for agave PKGBUILD

Awesome Lists containing this project

README 

        
ABOUT

=====

gnome-doc-utils is a collection of documentation utilities for the Gnome

project.  Notably, it contains utilities for building documentation and

all auxiliary files in your source tree, and it contains the DocBook

XSLT stylesheets that were once distributed with Yelp.  Starting with

Gnome 2.8, Yelp will require gnome-doc-utils for the XSLT.



ORGANIZATION

============

test/

	The test directory contains a number of tests for gnome-doc-utils.

	Directories of the form testdocn, where n is a positive integer,

	are skeleton source trees containing documentation, with the same

	layout that would be used by actual projects.



	The testdocs directory contains the unit tests from docbook-testdocs,

	developed by Norm and Co. for the pan-galactic DocBook stylesheets.

	An additional README file is in that directory, giving instructions

	on extending or changing any of the files in gnome-doc-utils CVS.



doc/

	The doc directory contains documentation for gnome-doc-utils.  In

	most cases, gnome-doc-utils is required to build its documentation.

	Mechanisms are in place for bootstrapping.



xslt/

	The xslt directory contains all of the XSLT in gnome-doc-utils.

	Notably, the xslt/docbook directory contains the DocBook XSLT,

	and xslt/gettext contains the XSLT gettext utility for translating

	automatic text.

   

sandbox/

	The sandbox directory is not DISTed, so it will only appear if you

	have a CVS checkout.  It's a playground for new ideas.



xml2po/

	The xml2po directory contains the xml2po tool developed by Danilo

	Segan for translation of arbitrary XML formats.  It is used by

	gnome-doc-utils for DocBook translation.



TESTING

=======

Under the test directory are a number of tests for gnome-doc-utils.  To

test the build system (gnome-doc-utils.m4 and gnome-doc-utils.make), you

can use any of the testdocn (for n a positive integer) directories.  These

are set up as skeleton source trees, behaving exactly as a real project

would.  Also, gnome-doc-utils uses itself to build its own documentation

(under doc), so gnome-doc-utils itself is a test of the build tools.



To test the DocBook stylesheets, use the test/testdocs directory.  These

unit tests are from the docbook-testdocs package on docbook.sourceforge.net,

developed by Norm and Co.  Simply typing make in that directory will build

each test.  If the name of the test file is foo.001.xml, the output will be

html/foo.001/foo.001.html.  Each test generally tests a small number of

related DocBook elements.  Many of the features of DocBook or of the XSLT

in gnome-doc-utils might not be tested by these.  Additional tests may

be added; follow the instructions in test/testdocs/README for that.



Also useful for testing the XSLT is to transform some large documents

using it.  The Gnome User Guide and the Gnumeric Manual both serve as

excellent test docs.



HACKING

=======

Unlike most C programming, working on much of gnome-doc-utils really does

involve isolated incremental improvements.  There's no way to give a short

list of broad features in a TODO list.



To work on the build tools (gnome-doc-utils.m4 and gnome-doc-utils.make),

build the test docs and see what doesn't work.  gnome-doc-utils.make has

a list of all the high-level targets that should be fully supported.



To work on the DocBook XSLT, find an element that isn't implemented yet and

implement it.  If you have XML Starlet (xmlstar.sourceforge.net) installed, 

you can type 'make report.html' in the xslt/docbook/html directory to get

a nice HTML report on what elements are implemented.  There is also a TODO

file in this directory with a very succinct list of matches that need to be

done that can't be caught by report.html.



Note that the XSLT is documented inline with xsldoc, which is itself a part

of gnome-doc-utils.  Feel free to work on xsldoc as well.  The documentation

generated by xsldoc is included in the manual under doc/xslt.



When in doubt, talk to Shaun McCance .  Never commit without

permission, unless Shaun has told you otherwise.  Wash behind your ears.  Don't

take candy from strangers.  Support independant musicicians.