+Mon Jun 25 12:41:30 CEST 2001 Daniel Veillard <Daniel.Veillard@imag.fr>
+
+ * libxslt/transform.[ch] libxslt/xslt.c libxslt/xsltInternals.h:
+ added a new interface xsltRunStylesheet() for a more flexible
+ handling of the output and trying to adhere to xsl:document
+ filename generation semantic if one knows the URL of the output,
+ also add IObuf capacity and SAX for output but is currently not
+ implemented.
+ * libxslt/xsltproc.c: added a -o or --output filename argument
+ to test xsltRunStylesheet() or provide a base when generating
+ multiple outputs
+ * tests/docbook/Makefile.am tests/docbook/result/xtchunk/html/*:
+ updated tests to add DocBook xt:document based chunking
+ * tests/multiple/Makefile.am: cleaned up the makefile a bit
+ * tests/multiple/out/*.html: the new xt:document now generate
+ the DOCTYPE if available as is the case for HTML
+
Mon Jun 25 08:45:00 HKT 2001 William Brack <wbrack@mmm.com.hk>
* Removed some redundant code in xsltDefaultProcessOneNode
*
* Process an XSLT-1.1 document element
*/
-void
+void
xsltDocumentElem(xsltTransformContextPtr ctxt, xmlNodePtr node,
- xmlNodePtr inst, xsltStylePreCompPtr comp) {
+ xmlNodePtr inst, xsltStylePreCompPtr comp)
+{
xsltStylesheetPtr style = NULL;
int ret;
- xmlChar *filename = NULL;
- xmlDocPtr result = NULL;
+ xmlChar *filename = NULL, *prop, *elements;
+ xmlChar *element, *end;
+ xmlDocPtr res = NULL;
xmlDocPtr oldOutput;
xmlNodePtr oldInsert;
+ const char *oldOutputFile;
+ xsltOutputType oldType;
+ xmlChar *URL = NULL;
+ const xmlChar *method;
+ const xmlChar *doctypePublic;
+ const xmlChar *doctypeSystem;
+ const xmlChar *version;
- if ((ctxt == NULL) || (node == NULL) || (inst == NULL) || (comp == NULL))
- return;
+ if ((ctxt == NULL) || (node == NULL) || (inst == NULL)
+ || (comp == NULL))
+ return;
if (comp->filename == NULL) {
- xmlChar *base = NULL;
- xmlChar *URL = NULL;
- if (xmlStrEqual(inst->name, (const xmlChar *) "output")) {
+
+ if (xmlStrEqual(inst->name, (const xmlChar *) "output")) {
#ifdef WITH_XSLT_DEBUG_EXTRA
- xsltGenericDebug(xsltGenericDebugContext,
- "Found saxon:output extension\n");
+ xsltGenericDebug(xsltGenericDebugContext,
+ "Found saxon:output extension\n");
#endif
- filename = xsltEvalAttrValueTemplate(ctxt, inst,
- (const xmlChar *)"file",
- XSLT_SAXON_NAMESPACE);
- } else if (xmlStrEqual(inst->name, (const xmlChar *) "write")) {
+ URL = xsltEvalAttrValueTemplate(ctxt, inst,
+ (const xmlChar *) "file",
+ XSLT_SAXON_NAMESPACE);
+ } else if (xmlStrEqual(inst->name, (const xmlChar *) "write")) {
#ifdef WITH_XSLT_DEBUG_EXTRA
- xsltGenericDebug(xsltGenericDebugContext,
- "Found xalan:write extension\n");
-#endif
- filename = xsltEvalAttrValueTemplate(ctxt, inst,
- (const xmlChar *)"select",
- XSLT_XALAN_NAMESPACE);
- } else if (xmlStrEqual(inst->name, (const xmlChar *) "document")) {
- filename = xsltEvalAttrValueTemplate(ctxt, inst,
- (const xmlChar *)"href",
- XSLT_XT_NAMESPACE);
- if (filename == NULL) {
+ xsltGenericDebug(xsltGenericDebugContext,
+ "Found xalan:write extension\n");
+#endif
+ URL = xsltEvalAttrValueTemplate(ctxt, inst,
+ (const xmlChar *)
+ "select",
+ XSLT_XALAN_NAMESPACE);
+ } else if (xmlStrEqual(inst->name, (const xmlChar *) "document")) {
+ URL = xsltEvalAttrValueTemplate(ctxt, inst,
+ (const xmlChar *) "href",
+ XSLT_XT_NAMESPACE);
+ if (URL == NULL) {
#ifdef WITH_XSLT_DEBUG_EXTRA
- xsltGenericDebug(xsltGenericDebugContext,
- "Found xslt11:document construct\n");
+ xsltGenericDebug(xsltGenericDebugContext,
+ "Found xslt11:document construct\n");
#endif
- filename = xsltEvalAttrValueTemplate(ctxt, inst,
- (const xmlChar *)"href",
- XSLT_NAMESPACE);
- comp->ver11 = 1;
- } else {
+ URL = xsltEvalAttrValueTemplate(ctxt, inst,
+ (const xmlChar *)
+ "href",
+ XSLT_NAMESPACE);
+ comp->ver11 = 1;
+ } else {
#ifdef WITH_XSLT_DEBUG_EXTRA
- xsltGenericDebug(xsltGenericDebugContext,
- "Found xt:document extension\n");
+ xsltGenericDebug(xsltGenericDebugContext,
+ "Found xt:document extension\n");
#endif
- comp->ver11 = 0;
- }
- }
- if (filename == NULL)
- return;
+ comp->ver11 = 0;
+ }
+ }
- /*
- * Compute output URL
- */
- base = xmlNodeGetBase(inst->doc, inst);
- URL = xmlBuildURI(filename, base);
- if (URL == NULL) {
- xsltGenericError(xsltGenericErrorContext,
- "xsltDocumentElem: URL computation failed %s\n", filename);
- } else {
- xmlFree(filename);
- filename = URL;
- }
- if (base != NULL)
- xmlFree(base);
} else {
- filename = xmlStrdup(comp->filename);
+ URL = xmlStrdup(comp->filename);
+ }
+
+ if (URL == NULL) {
+ xsltGenericError(xsltGenericErrorContext,
+ "xsltDocumentElem: href/URI-Reference not found\n");
+ return;
+ }
+ filename = xmlBuildURI(URL, (const xmlChar *) ctxt->outputFile);
+ if (filename == NULL) {
+ xsltGenericError(xsltGenericErrorContext,
+ "xsltDocumentElem: URL computation failed for %s\n",
+ URL);
+ xmlFree(URL);
+ return;
}
+ oldOutputFile = ctxt->outputFile;
oldOutput = ctxt->output;
oldInsert = ctxt->insert;
+ oldType = ctxt->type;
+ ctxt->outputFile = (const char *) filename;
style = xsltNewStylesheet();
if (style == NULL) {
- xsltGenericError(xsltGenericErrorContext,
- "xsltDocumentElem: out of memory\n");
- goto error;
+ xsltGenericError(xsltGenericErrorContext,
+ "xsltDocumentElem: out of memory\n");
+ goto error;
}
/*
* Version described in 1.1 draft allows full parametrization
* of the output.
*/
- xsltParseStylesheetOutput(style, inst);
+ if (comp->ver11) {
+ prop = xsltEvalAttrValueTemplate(ctxt, inst,
+ (const xmlChar *) "version",
+ XSLT_NAMESPACE);
+ if (prop != NULL) {
+ if (style->version != NULL)
+ xmlFree(style->version);
+ style->version = prop;
+ }
+ prop = xsltEvalAttrValueTemplate(ctxt, inst,
+ (const xmlChar *) "encoding",
+ XSLT_NAMESPACE);
+ if (prop != NULL) {
+ if (style->encoding != NULL)
+ xmlFree(style->encoding);
+ style->encoding = prop;
+ }
+ prop = xsltEvalAttrValueTemplate(ctxt, inst,
+ (const xmlChar *) "method",
+ XSLT_NAMESPACE);
+ if (prop != NULL) {
+ xmlChar *ncname;
+ xmlChar *prefix = NULL;
+
+ if (style->method != NULL)
+ xmlFree(style->method);
+ style->method = NULL;
+ if (style->methodURI != NULL)
+ xmlFree(style->methodURI);
+ style->methodURI = NULL;
+
+ ncname = xmlSplitQName2(prop, &prefix);
+ if (ncname != NULL) {
+ if (prefix != NULL) {
+ xmlNsPtr ns;
+
+ ns = xmlSearchNs(inst->doc, inst, prefix);
+ if (ns == NULL) {
+ xsltGenericError(xsltGenericErrorContext,
+ "no namespace bound to prefix %s\n",
+ prefix);
+ style->warnings++;
+ xmlFree(prefix);
+ xmlFree(ncname);
+ style->method = prop;
+ } else {
+ style->methodURI = xmlStrdup(ns->href);
+ style->method = ncname;
+ xmlFree(prefix);
+ xmlFree(prop);
+ }
+ } else {
+ style->method = ncname;
+ xmlFree(prop);
+ }
+ } else {
+ if ((xmlStrEqual(prop, (const xmlChar *) "xml")) ||
+ (xmlStrEqual(prop, (const xmlChar *) "html")) ||
+ (xmlStrEqual(prop, (const xmlChar *) "text"))) {
+ style->method = prop;
+ } else {
+ xsltGenericError(xsltGenericErrorContext,
+ "invalid value for method: %s\n",
+ prop);
+ style->warnings++;
+ }
+ }
+ }
+ prop = xsltEvalAttrValueTemplate(ctxt, inst,
+ (const xmlChar *)
+ "doctype-system", XSLT_NAMESPACE);
+ if (prop != NULL) {
+ if (style->doctypeSystem != NULL)
+ xmlFree(style->doctypeSystem);
+ style->doctypeSystem = prop;
+ }
+ prop = xsltEvalAttrValueTemplate(ctxt, inst,
+ (const xmlChar *)
+ "doctype-public", XSLT_NAMESPACE);
+ if (prop != NULL) {
+ if (style->doctypePublic != NULL)
+ xmlFree(style->doctypePublic);
+ style->doctypePublic = prop;
+ }
+ prop = xsltEvalAttrValueTemplate(ctxt, inst,
+ (const xmlChar *) "standalone",
+ XSLT_NAMESPACE);
+ if (prop != NULL) {
+ if (xmlStrEqual(prop, (const xmlChar *) "yes")) {
+ style->standalone = 1;
+ } else if (xmlStrEqual(prop, (const xmlChar *) "no")) {
+ style->standalone = 0;
+ } else {
+ xsltGenericError(xsltGenericErrorContext,
+ "invalid value for standalone: %s\n",
+ prop);
+ style->warnings++;
+ }
+ xmlFree(prop);
+ }
+
+ prop = xsltEvalAttrValueTemplate(ctxt, inst,
+ (const xmlChar *) "indent",
+ XSLT_NAMESPACE);
+ if (prop != NULL) {
+ if (xmlStrEqual(prop, (const xmlChar *) "yes")) {
+ style->indent = 1;
+ } else if (xmlStrEqual(prop, (const xmlChar *) "no")) {
+ style->indent = 0;
+ } else {
+ xsltGenericError(xsltGenericErrorContext,
+ "invalid value for indent: %s\n", prop);
+ style->warnings++;
+ }
+ xmlFree(prop);
+ }
+
+ prop = xsltEvalAttrValueTemplate(ctxt, inst,
+ (const xmlChar *)
+ "omit-xml-declaration",
+ XSLT_NAMESPACE);
+ if (prop != NULL) {
+ if (xmlStrEqual(prop, (const xmlChar *) "yes")) {
+ style->omitXmlDeclaration = 1;
+ } else if (xmlStrEqual(prop, (const xmlChar *) "no")) {
+ style->omitXmlDeclaration = 0;
+ } else {
+ xsltGenericError(xsltGenericErrorContext,
+ "invalid value for omit-xml-declaration: %s\n",
+ prop);
+ style->warnings++;
+ }
+ xmlFree(prop);
+ }
+
+ elements = xsltEvalAttrValueTemplate(ctxt, inst,
+ (const xmlChar *)
+ "cdata-section-elements",
+ XSLT_NAMESPACE);
+ if (elements != NULL) {
+ if (style->stripSpaces == NULL)
+ style->stripSpaces = xmlHashCreate(10);
+ if (style->stripSpaces == NULL)
+ return;
+
+ element = elements;
+ while (*element != 0) {
+ while (IS_BLANK(*element))
+ element++;
+ if (*element == 0)
+ break;
+ end = element;
+ while ((*end != 0) && (!IS_BLANK(*end)))
+ end++;
+ element = xmlStrndup(element, end - element);
+ if (element) {
+#ifdef WITH_XSLT_DEBUG_PARSING
+ xsltGenericDebug(xsltGenericDebugContext,
+ "add cdata section output element %s\n",
+ element);
+#endif
+ xmlHashAddEntry(style->stripSpaces, element,
+ (xmlChar *) "cdata");
+ xmlFree(element);
+ }
+ element = end;
+ }
+ xmlFree(elements);
+ }
+ } else {
+ xsltParseStylesheetOutput(style, inst);
+ }
/*
* Create a new document tree and process the element template
*/
- result = xmlNewDoc(style->version);
- if (result == NULL) {
- xsltGenericError(xsltGenericErrorContext,
- "xsltDocumentElem: out of memory\n");
- goto error;
+ XSLT_GET_IMPORT_PTR(method, style, method)
+ XSLT_GET_IMPORT_PTR(doctypePublic, style, doctypePublic)
+ XSLT_GET_IMPORT_PTR(doctypeSystem, style, doctypeSystem)
+ XSLT_GET_IMPORT_PTR(version, style, version)
+
+ if ((method != NULL) &&
+ (!xmlStrEqual(method, (const xmlChar *) "xml"))) {
+ if (xmlStrEqual(method, (const xmlChar *) "html")) {
+ ctxt->type = XSLT_OUTPUT_HTML;
+ if (((doctypePublic != NULL) || (doctypeSystem != NULL)))
+ res = htmlNewDoc(doctypeSystem, doctypePublic);
+ else {
+ if (version == NULL)
+ version = (const xmlChar *) "4.0";
+#ifdef XSLT_GENERATE_HTML_DOCTYPE
+ xsltGetHTMLIDs(version, &doctypePublic, &doctypeSystem);
+#endif
+ res = htmlNewDoc(doctypeSystem, doctypePublic);
+ }
+ if (res == NULL)
+ goto error;
+ } else if (xmlStrEqual(method, (const xmlChar *) "xhtml")) {
+ xsltGenericError(xsltGenericErrorContext,
+ "xsltApplyStylesheet: unsupported method xhtml, using html\n",
+ style->method);
+ ctxt->type = XSLT_OUTPUT_HTML;
+ res = htmlNewDoc(doctypeSystem, doctypePublic);
+ if (res == NULL)
+ goto error;
+ } else if (xmlStrEqual(style->method, (const xmlChar *) "text")) {
+ ctxt->type = XSLT_OUTPUT_TEXT;
+ res = xmlNewDoc(style->version);
+ if (res == NULL)
+ goto error;
+ } else {
+ xsltGenericError(xsltGenericErrorContext,
+ "xsltApplyStylesheet: unsupported method %s\n",
+ style->method);
+ goto error;
+ }
+ } else {
+ ctxt->type = XSLT_OUTPUT_XML;
+ res = xmlNewDoc(style->version);
+ if (res == NULL)
+ goto error;
}
- ctxt->output = result;
- ctxt->insert = (xmlNodePtr) result;
+ res->charset = XML_CHAR_ENCODING_UTF8;
+ if (style->encoding != NULL)
+ res->encoding = xmlStrdup(style->encoding);
+ ctxt->output = res;
+ ctxt->insert = (xmlNodePtr) res;
varsPush(ctxt, NULL);
xsltApplyOneTemplate(ctxt, node, inst->children, 0);
xsltFreeStackElemList(varsPop(ctxt));
/*
- * Save the result
+ * Save the res
*/
ret = xsltSaveResultToFilename((const char *) filename,
- result, style, 0);
+ res, style, 0);
if (ret < 0) {
- xsltGenericError(xsltGenericErrorContext,
- "xsltDocumentElem: unable to save to %s\n", filename);
+ xsltGenericError(xsltGenericErrorContext,
+ "xsltDocumentElem: unable to save to %s\n",
+ filename);
#ifdef WITH_XSLT_DEBUG_EXTRA
} else {
- xsltGenericDebug(xsltGenericDebugContext,
- "Wrote %d bytes to %s\n", ret, , filename);
+ xsltGenericDebug(xsltGenericDebugContext,
+ "Wrote %d bytes to %s\n", ret,, filename);
#endif
}
-error:
+ error:
ctxt->output = oldOutput;
ctxt->insert = oldInsert;
+ ctxt->type = oldType;
+ ctxt->outputFile = oldOutputFile;
+ if (URL != NULL)
+ xmlFree(URL);
if (filename != NULL)
xmlFree(filename);
if (style != NULL)
- xsltFreeStylesheet(style);
- if (result != NULL)
- xmlFreeDoc(result);
+ xsltFreeStylesheet(style);
+ if (res != NULL)
+ xmlFreeDoc(res);
}
/************************************************************************
const xmlChar *oldMode, *oldModeURI;
xsltStackElemPtr params = NULL, param, tmp, p;
int nbsorts = 0;
- int newdoc = 0;
xmlNodePtr sorts[XSLT_MAX_SORT];
xmlDocPtr oldXDocPtr;
xsltDocumentPtr oldCDocPtr;
xmlNodePtr oldNode = ctxt->node;
int nbsorts = 0;
xmlNodePtr sorts[XSLT_MAX_SORT];
- xmlDocPtr oldXDocPtr, newXDocPtr;
- xsltDocumentPtr oldCDocPtr, newCDocPtr;
+ xmlDocPtr oldXDocPtr;
+ xsltDocumentPtr oldCDocPtr;
if ((ctxt == NULL) || (node == NULL) || (inst == NULL))
return;
#endif
/**
- * xsltApplyStylesheet:
+ * xsltApplyStylesheetInternal:
* @style: a parsed XSLT stylesheet
* @doc: a parsed XML document
* @params: a NULL terminated arry of parameters names/values tuples
+ * @output: the targetted output
*
* Apply the stylesheet to the document
* NOTE: This may lead to a non-wellformed output XML wise !
*
* Returns the result document or NULL in case of error
*/
-xmlDocPtr
-xsltApplyStylesheet(xsltStylesheetPtr style, xmlDocPtr doc,
- const char **params) {
+static xmlDocPtr
+xsltApplyStylesheetInternal(xsltStylesheetPtr style, xmlDocPtr doc,
+ const char **params, const char *output) {
xmlDocPtr res = NULL;
xsltTransformContextPtr ctxt = NULL;
xmlNodePtr root;
if ((style == NULL) || (doc == NULL))
return(NULL);
ctxt = xsltNewTransformContext(style, doc);
- xsltRegisterExtras(ctxt);
if (ctxt == NULL)
return(NULL);
+ xsltRegisterExtras(ctxt);
+ if (output != NULL)
+ ctxt->outputFile = output;
+ else
+ ctxt->outputFile = NULL;
XSLT_GET_IMPORT_PTR(method, style, method)
XSLT_GET_IMPORT_PTR(doctypePublic, style, doctypePublic)
return(NULL);
}
+/**
+ * xsltApplyStylesheet:
+ * @style: a parsed XSLT stylesheet
+ * @doc: a parsed XML document
+ * @params: a NULL terminated arry of parameters names/values tuples
+ *
+ * Apply the stylesheet to the document
+ * NOTE: This may lead to a non-wellformed output XML wise !
+ *
+ * Returns the result document or NULL in case of error
+ */
+xmlDocPtr
+xsltApplyStylesheet(xsltStylesheetPtr style, xmlDocPtr doc,
+ const char **params) {
+ return(xsltApplyStylesheetInternal(style, doc, params, NULL));
+}
+
+/**
+ * xsltRunStylesheet:
+ * @style: a parsed XSLT stylesheet
+ * @doc: a parsed XML document
+ * @params: a NULL terminated arry of parameters names/values tuples
+ * @output: the URL/filename ot the generated resource if available
+ * @SAX: a SAX handler for progressive callback output (not implemented yet)
+ * @IObuf: an output buffer for progressive output (not implemented yet)
+ *
+ * Apply the stylesheet to the document and generate the output according
+ * to @output @SAX and @IObuf. It's an error to specify both @SAX and @IObuf.
+ *
+ * NOTE: This may lead to a non-wellformed output XML wise !
+ * NOTE: This may also result in multiple files being generated
+ * NOTE: using IObuf, the result encoding used will be the one used for
+ * creating the output buffer, use the following macro to read it
+ * from the stylesheet
+ * XSLT_GET_IMPORT_PTR(encoding, style, encoding)
+ * NOTE: using SAX, any encoding specified in the stylesheet will be lost
+ * since the interface uses only UTF8
+ *
+ * Returns the number of by written to the main resource or -1 in case of
+ * error.
+ */
+int
+xsltRunStylesheet(xsltStylesheetPtr style, xmlDocPtr doc, const char **params,
+ const char *output, xmlSAXHandlerPtr SAX,
+ xmlOutputBufferPtr IObuf)
+{
+ xmlDocPtr tmp;
+ int ret;
+
+ if ((output == NULL) && (SAX == NULL) && (IObuf == NULL))
+ return(-1);
+ if ((SAX != NULL) && (IObuf != NULL))
+ return(-1);
+
+ /* unsupported yet */
+ if (SAX != NULL) {
+ TODO /* xsltRunStylesheet xmlSAXHandlerPtr SAX */
+ return(-1);
+ }
+
+ tmp = xsltApplyStylesheetInternal(style, doc, params, output);
+ if (tmp == NULL) {
+ xsltGenericError(xsltGenericErrorContext,
+ "xsltRunStylesheet : run failed\n");
+ return(-1);
+ }
+ if (IObuf != NULL) {
+ /* TODO: incomplete, IObuf output not progressive */
+ ret = xsltSaveResultTo(IObuf, tmp, style);
+ } else {
+ ret = xsltSaveResultToFilename(output, tmp, style, 0);
+ }
+ xmlFreeDoc(tmp);
+ return(ret);
+}
#ifndef __XML_XSLT_TRANSFORM_H__
#define __XML_XSLT_TRANSFORM_H__
-#include <libxml/tree.h>
+#include <libxml/parser.h>
+#include <libxml/xmlIO.h>
#ifdef __cplusplus
extern "C" {
xmlDocPtr xsltApplyStylesheet (xsltStylesheetPtr style,
xmlDocPtr doc,
const char **params);
+int xsltRunStylesheet (xsltStylesheetPtr style,
+ xmlDocPtr doc,
+ const char **params,
+ const char *output,
+ xmlSAXHandlerPtr SAX,
+ xmlOutputBufferPtr IObuf);
void xsltApplyOneTemplate (xsltTransformContextPtr ctxt,
xmlNodePtr node,
xmlNodePtr list,
* Free up the memory allocated by @sheet
*/
void
-xsltFreeStylesheet(xsltStylesheetPtr sheet) {
+xsltFreeStylesheet(xsltStylesheetPtr sheet)
+{
if (sheet == NULL)
- return;
+ return;
xsltFreeKeys(sheet);
xsltFreeExts(sheet);
xsltFreeStyleDocuments(sheet);
xsltFreeStylePreComps(sheet);
if (sheet->doc != NULL)
- xmlFreeDoc(sheet->doc);
+ xmlFreeDoc(sheet->doc);
if (sheet->variables != NULL)
- xsltFreeStackElemList(sheet->variables);
+ xsltFreeStackElemList(sheet->variables);
if (sheet->stripSpaces != NULL)
- xmlHashFree(sheet->stripSpaces, NULL);
- if (sheet->nsHash != NULL)
- xmlHashFree(sheet->nsHash, NULL);
-
- if (sheet->method != NULL) xmlFree(sheet->method);
- if (sheet->methodURI != NULL) xmlFree(sheet->methodURI);
- if (sheet->version != NULL) xmlFree(sheet->version);
- if (sheet->encoding != NULL) xmlFree(sheet->encoding);
- if (sheet->doctypePublic != NULL) xmlFree(sheet->doctypePublic);
- if (sheet->doctypeSystem != NULL) xmlFree(sheet->doctypeSystem);
- if (sheet->mediaType != NULL) xmlFree(sheet->mediaType);
+ xmlHashFree(sheet->stripSpaces, NULL);
+ if (sheet->nsHash != NULL)
+ xmlHashFree(sheet->nsHash, NULL);
+
+ if (sheet->method != NULL)
+ xmlFree(sheet->method);
+ if (sheet->methodURI != NULL)
+ xmlFree(sheet->methodURI);
+ if (sheet->version != NULL)
+ xmlFree(sheet->version);
+ if (sheet->encoding != NULL)
+ xmlFree(sheet->encoding);
+ if (sheet->doctypePublic != NULL)
+ xmlFree(sheet->doctypePublic);
+ if (sheet->doctypeSystem != NULL)
+ xmlFree(sheet->doctypeSystem);
+ if (sheet->mediaType != NULL)
+ xmlFree(sheet->mediaType);
if (sheet->imports != NULL)
- xsltFreeStylesheetList(sheet->imports);
+ xsltFreeStylesheetList(sheet->imports);
memset(sheet, -1, sizeof(xsltStylesheet));
xmlFree(sheet);
*/
void
-xsltParseStylesheetOutput(xsltStylesheetPtr style, xmlNodePtr cur) {
- xmlChar *elements, *prop;
- xmlChar *element, *end;
+xsltParseStylesheetOutput(xsltStylesheetPtr style, xmlNodePtr cur)
+{
+ xmlChar *elements,
+ *prop;
+ xmlChar *element,
+ *end;
if ((cur == NULL) || (style == NULL))
- return;
+ return;
- prop = xsltGetNsProp(cur, (const xmlChar *)"version", XSLT_NAMESPACE);
+ prop = xsltGetNsProp(cur, (const xmlChar *) "version", XSLT_NAMESPACE);
if (prop != NULL) {
- if (style->version != NULL) xmlFree(style->version);
- style->version = prop;
+ if (style->version != NULL)
+ xmlFree(style->version);
+ style->version = prop;
}
- prop = xsltGetNsProp(cur, (const xmlChar *)"encoding", XSLT_NAMESPACE);
+ prop =
+ xsltGetNsProp(cur, (const xmlChar *) "encoding", XSLT_NAMESPACE);
if (prop != NULL) {
- if (style->encoding != NULL) xmlFree(style->encoding);
- style->encoding = prop;
+ if (style->encoding != NULL)
+ xmlFree(style->encoding);
+ style->encoding = prop;
}
/* relaxed to support xt:document */
- prop = xmlGetProp(cur, (const xmlChar *)"method");
+ prop = xmlGetProp(cur, (const xmlChar *) "method");
if (prop != NULL) {
- xmlChar *ncname;
- xmlChar *prefix = NULL;
-
- if (style->method != NULL) xmlFree(style->method);
- style->method = NULL;
- if (style->methodURI != NULL) xmlFree(style->methodURI);
- style->methodURI = NULL;
-
- ncname = xmlSplitQName2(prop, &prefix);
- if (ncname != NULL) {
- if (prefix != NULL) {
- xmlNsPtr ns;
-
- ns = xmlSearchNs(cur->doc, cur, prefix);
- if (ns == NULL) {
- xsltGenericError(xsltGenericErrorContext,
- "no namespace bound to prefix %s\n", prefix);
- style->warnings++;
- xmlFree(prefix);
- xmlFree(ncname);
- style->method = prop;
- } else {
- style->methodURI = xmlStrdup(ns->href);
- style->method = ncname;
- xmlFree(prefix);
- xmlFree(prop);
- }
- } else {
- style->method = ncname;
- xmlFree(prop);
- }
- } else {
- if ((xmlStrEqual(prop, (const xmlChar *)"xml")) ||
- (xmlStrEqual(prop, (const xmlChar *)"html")) ||
- (xmlStrEqual(prop, (const xmlChar *)"text"))) {
- style->method = prop;
- } else {
- xsltGenericError(xsltGenericErrorContext,
- "invalid value for method: %s\n", prop);
- style->warnings++;
- }
- }
+ xmlChar *ncname;
+ xmlChar *prefix = NULL;
+
+ if (style->method != NULL)
+ xmlFree(style->method);
+ style->method = NULL;
+ if (style->methodURI != NULL)
+ xmlFree(style->methodURI);
+ style->methodURI = NULL;
+
+ ncname = xmlSplitQName2(prop, &prefix);
+ if (ncname != NULL) {
+ if (prefix != NULL) {
+ xmlNsPtr ns;
+
+ ns = xmlSearchNs(cur->doc, cur, prefix);
+ if (ns == NULL) {
+ xsltGenericError(xsltGenericErrorContext,
+ "no namespace bound to prefix %s\n",
+ prefix);
+ style->warnings++;
+ xmlFree(prefix);
+ xmlFree(ncname);
+ style->method = prop;
+ } else {
+ style->methodURI = xmlStrdup(ns->href);
+ style->method = ncname;
+ xmlFree(prefix);
+ xmlFree(prop);
+ }
+ } else {
+ style->method = ncname;
+ xmlFree(prop);
+ }
+ } else {
+ if ((xmlStrEqual(prop, (const xmlChar *) "xml")) ||
+ (xmlStrEqual(prop, (const xmlChar *) "html")) ||
+ (xmlStrEqual(prop, (const xmlChar *) "text"))) {
+ style->method = prop;
+ } else {
+ xsltGenericError(xsltGenericErrorContext,
+ "invalid value for method: %s\n", prop);
+ style->warnings++;
+ }
+ }
}
- prop = xsltGetNsProp(cur, (const xmlChar *)"doctype-system", XSLT_NAMESPACE);
+ prop =
+ xsltGetNsProp(cur, (const xmlChar *) "doctype-system",
+ XSLT_NAMESPACE);
if (prop != NULL) {
- if (style->doctypeSystem != NULL) xmlFree(style->doctypeSystem);
- style->doctypeSystem = prop;
+ if (style->doctypeSystem != NULL)
+ xmlFree(style->doctypeSystem);
+ style->doctypeSystem = prop;
}
- prop = xsltGetNsProp(cur, (const xmlChar *)"doctype-public", XSLT_NAMESPACE);
+ prop =
+ xsltGetNsProp(cur, (const xmlChar *) "doctype-public",
+ XSLT_NAMESPACE);
if (prop != NULL) {
- if (style->doctypePublic != NULL) xmlFree(style->doctypePublic);
- style->doctypePublic = prop;
+ if (style->doctypePublic != NULL)
+ xmlFree(style->doctypePublic);
+ style->doctypePublic = prop;
}
- prop = xsltGetNsProp(cur, (const xmlChar *)"standalone",
- XSLT_NAMESPACE);
+ prop = xsltGetNsProp(cur, (const xmlChar *) "standalone",
+ XSLT_NAMESPACE);
if (prop != NULL) {
- if (xmlStrEqual(prop, (const xmlChar *)"yes")) {
- style->standalone = 1;
- } else if (xmlStrEqual(prop, (const xmlChar *)"no")) {
- style->standalone = 0;
- } else {
- xsltGenericError(xsltGenericErrorContext,
- "invalid value for standalone: %s\n", prop);
- style->warnings++;
- }
- xmlFree(prop);
+ if (xmlStrEqual(prop, (const xmlChar *) "yes")) {
+ style->standalone = 1;
+ } else if (xmlStrEqual(prop, (const xmlChar *) "no")) {
+ style->standalone = 0;
+ } else {
+ xsltGenericError(xsltGenericErrorContext,
+ "invalid value for standalone: %s\n", prop);
+ style->warnings++;
+ }
+ xmlFree(prop);
}
- prop = xsltGetNsProp(cur, (const xmlChar *)"indent",
- XSLT_NAMESPACE);
+ prop = xsltGetNsProp(cur, (const xmlChar *) "indent", XSLT_NAMESPACE);
if (prop != NULL) {
- if (xmlStrEqual(prop, (const xmlChar *)"yes")) {
- style->indent = 1;
- } else if (xmlStrEqual(prop, (const xmlChar *)"no")) {
- style->indent = 0;
- } else {
- xsltGenericError(xsltGenericErrorContext,
- "invalid value for indent: %s\n", prop);
- style->warnings++;
- }
- xmlFree(prop);
+ if (xmlStrEqual(prop, (const xmlChar *) "yes")) {
+ style->indent = 1;
+ } else if (xmlStrEqual(prop, (const xmlChar *) "no")) {
+ style->indent = 0;
+ } else {
+ xsltGenericError(xsltGenericErrorContext,
+ "invalid value for indent: %s\n", prop);
+ style->warnings++;
+ }
+ xmlFree(prop);
}
- prop = xsltGetNsProp(cur, (const xmlChar *)"omit-xml-declaration",
- XSLT_NAMESPACE);
+ prop = xsltGetNsProp(cur, (const xmlChar *) "omit-xml-declaration",
+ XSLT_NAMESPACE);
if (prop != NULL) {
- if (xmlStrEqual(prop, (const xmlChar *)"yes")) {
- style->omitXmlDeclaration = 1;
- } else if (xmlStrEqual(prop, (const xmlChar *)"no")) {
- style->omitXmlDeclaration = 0;
- } else {
- xsltGenericError(xsltGenericErrorContext,
- "invalid value for omit-xml-declaration: %s\n", prop);
- style->warnings++;
- }
- xmlFree(prop);
+ if (xmlStrEqual(prop, (const xmlChar *) "yes")) {
+ style->omitXmlDeclaration = 1;
+ } else if (xmlStrEqual(prop, (const xmlChar *) "no")) {
+ style->omitXmlDeclaration = 0;
+ } else {
+ xsltGenericError(xsltGenericErrorContext,
+ "invalid value for omit-xml-declaration: %s\n",
+ prop);
+ style->warnings++;
+ }
+ xmlFree(prop);
}
- elements = xsltGetNsProp(cur, (const xmlChar *)"cdata-section-elements",
- XSLT_NAMESPACE);
+ elements =
+ xsltGetNsProp(cur, (const xmlChar *) "cdata-section-elements",
+ XSLT_NAMESPACE);
if (elements != NULL) {
- if (style->stripSpaces == NULL)
- style->stripSpaces = xmlHashCreate(10);
- if (style->stripSpaces == NULL)
- return;
-
- element = elements;
- while (*element != 0) {
- while (IS_BLANK(*element)) element++;
- if (*element == 0)
- break;
- end = element;
- while ((*end != 0) && (!IS_BLANK(*end))) end++;
- element = xmlStrndup(element, end - element);
- if (element) {
+ if (style->stripSpaces == NULL)
+ style->stripSpaces = xmlHashCreate(10);
+ if (style->stripSpaces == NULL)
+ return;
+
+ element = elements;
+ while (*element != 0) {
+ while (IS_BLANK(*element))
+ element++;
+ if (*element == 0)
+ break;
+ end = element;
+ while ((*end != 0) && (!IS_BLANK(*end)))
+ end++;
+ element = xmlStrndup(element, end - element);
+ if (element) {
#ifdef WITH_XSLT_DEBUG_PARSING
- xsltGenericDebug(xsltGenericDebugContext,
- "add cdata section output element %s\n", element);
+ xsltGenericDebug(xsltGenericDebugContext,
+ "add cdata section output element %s\n",
+ element);
#endif
- xmlHashAddEntry(style->stripSpaces, element,
- (xmlChar *) "cdata");
- xmlFree(element);
- }
- element = end;
- }
- xmlFree(elements);
+ xmlHashAddEntry(style->stripSpaces, element,
+ (xmlChar *) "cdata");
+ xmlFree(element);
+ }
+ element = end;
+ }
+ xmlFree(elements);
}
}
xmlNodePtr inst; /* the instruction in the stylesheet */
int xinclude; /* should XInclude be processed */
+
+ const char * outputFile; /* the output URI if known */
};
/**
printf(" Options:\n");
printf(" --version or -V: show the version of libxml and libxslt used\n");
printf(" --verbose or -v: show logs of what's happening\n");
+ printf(" --output file or -v file: save to a given file\n");
printf(" --timing: display the time used\n");
printf(" --repeat: run the transformation 20 times\n");
printf(" --debug: dump the tree of the result instead\n");
}
int
-main(int argc, char **argv) {
+main(int argc, char **argv)
+{
int i;
xsltStylesheetPtr cur = NULL;
xmlDocPtr doc, res;
struct timeval begin, end;
const char *params[16 + 1];
int nbparams = 0;
+ const char *output = NULL;
if (argc <= 1) {
- usage(argv[0]);
- return(1);
+ usage(argv[0]);
+ return (1);
}
xmlInitMemory();
- LIBXML_TEST_VERSION
- defaultLoader = xmlGetExternalEntityLoader();
- for (i = 1; i < argc ; i++) {
- if (!strcmp(argv[i], "-"))
- break;
+ LIBXML_TEST_VERSION defaultLoader = xmlGetExternalEntityLoader();
+ for (i = 1; i < argc; i++) {
+ if (!strcmp(argv[i], "-"))
+ break;
- if (argv[i][0] != '-')
- continue;
+ if (argv[i][0] != '-')
+ continue;
#ifdef LIBXML_DEBUG_ENABLED
- if ((!strcmp(argv[i], "-debug")) || (!strcmp(argv[i], "--debug"))) {
- debug++;
- } else
+ if ((!strcmp(argv[i], "-debug")) || (!strcmp(argv[i], "--debug"))) {
+ debug++;
+ } else
#endif
- if ((!strcmp(argv[i], "-v")) ||
- (!strcmp(argv[i], "-verbose")) ||
- (!strcmp(argv[i], "--verbose"))) {
- xsltSetGenericDebugFunc(stderr, NULL);
- } else if ((!strcmp(argv[i], "-V")) ||
- (!strcmp(argv[i], "-version")) ||
- (!strcmp(argv[i], "--version"))) {
- printf("Using libxml %s and libxslt %s\n",
- xmlParserVersion, xsltEngineVersion);
- printf("xsltproc was compiled against libxml %d and libxslt %d\n",
- LIBXML_VERSION, LIBXSLT_VERSION);
- printf("libxslt %d was compiled against libxml %d\n",
- xsltLibxsltVersion, xsltLibxmlVersion);
- } else if ((!strcmp(argv[i], "-repeat")) ||
- (!strcmp(argv[i], "--repeat"))) {
- if (repeat == 0)
- repeat = 20;
- else
- repeat = 100;
- } else if ((!strcmp(argv[i], "-novalid")) ||
- (!strcmp(argv[i], "--novalid"))) {
- novalid++;
- } else if ((!strcmp(argv[i], "-noout")) ||
- (!strcmp(argv[i], "--noout"))) {
- noout++;
+ if ((!strcmp(argv[i], "-v")) ||
+ (!strcmp(argv[i], "-verbose")) ||
+ (!strcmp(argv[i], "--verbose"))) {
+ xsltSetGenericDebugFunc(stderr, NULL);
+ } else if ((!strcmp(argv[i], "-o")) ||
+ (!strcmp(argv[i], "-output")) ||
+ (!strcmp(argv[i], "--output"))) {
+ i++;
+ output = argv[i++];
+ } else if ((!strcmp(argv[i], "-V")) ||
+ (!strcmp(argv[i], "-version")) ||
+ (!strcmp(argv[i], "--version"))) {
+ printf("Using libxml %s and libxslt %s\n",
+ xmlParserVersion, xsltEngineVersion);
+ printf
+ ("xsltproc was compiled against libxml %d and libxslt %d\n",
+ LIBXML_VERSION, LIBXSLT_VERSION);
+ printf("libxslt %d was compiled against libxml %d\n",
+ xsltLibxsltVersion, xsltLibxmlVersion);
+ } else if ((!strcmp(argv[i], "-repeat"))
+ || (!strcmp(argv[i], "--repeat"))) {
+ if (repeat == 0)
+ repeat = 20;
+ else
+ repeat = 100;
+ } else if ((!strcmp(argv[i], "-novalid")) ||
+ (!strcmp(argv[i], "--novalid"))) {
+ novalid++;
+ } else if ((!strcmp(argv[i], "-noout")) ||
+ (!strcmp(argv[i], "--noout"))) {
+ noout++;
#ifdef LIBXML_DOCB_ENABLED
- } else if ((!strcmp(argv[i], "-docbook")) ||
- (!strcmp(argv[i], "--docbook"))) {
- docbook++;
+ } else if ((!strcmp(argv[i], "-docbook")) ||
+ (!strcmp(argv[i], "--docbook"))) {
+ docbook++;
#endif
#ifdef LIBXML_HTML_ENABLED
- } else if ((!strcmp(argv[i], "-html")) ||
- (!strcmp(argv[i], "--html"))) {
- html++;
+ } else if ((!strcmp(argv[i], "-html")) ||
+ (!strcmp(argv[i], "--html"))) {
+ html++;
#endif
- } else if ((!strcmp(argv[i], "-timing")) ||
- (!strcmp(argv[i], "--timing"))) {
- timing++;
- } else if ((!strcmp(argv[i], "-warnnet")) ||
- (!strcmp(argv[i], "--warnnet"))) {
- xmlSetExternalEntityLoader(xsltNoNetExternalEntityLoader);
- } else if ((!strcmp(argv[i], "-nonet")) ||
- (!strcmp(argv[i], "--nonet"))) {
- xmlSetExternalEntityLoader(xsltNoNetExternalEntityLoader);
- nonet = 1;
+ } else if ((!strcmp(argv[i], "-timing")) ||
+ (!strcmp(argv[i], "--timing"))) {
+ timing++;
+ } else if ((!strcmp(argv[i], "-warnnet")) ||
+ (!strcmp(argv[i], "--warnnet"))) {
+ xmlSetExternalEntityLoader(xsltNoNetExternalEntityLoader);
+ } else if ((!strcmp(argv[i], "-nonet")) ||
+ (!strcmp(argv[i], "--nonet"))) {
+ xmlSetExternalEntityLoader(xsltNoNetExternalEntityLoader);
+ nonet = 1;
#ifdef LIBXML_CATALOG_ENABLED
- } else if ((!strcmp(argv[i], "-catalogs")) ||
- (!strcmp(argv[i], "--catalogs"))) {
- const char *catalogs;
+ } else if ((!strcmp(argv[i], "-catalogs")) ||
+ (!strcmp(argv[i], "--catalogs"))) {
+ const char *catalogs;
- catalogs = getenv("SGML_CATALOG_FILES");
- if (catalogs == NULL) {
- fprintf(stderr, "Variable $SGML_CATALOG_FILES not set\n");
- } else {
- xmlLoadCatalogs(catalogs);
- }
+ catalogs = getenv("SGML_CATALOG_FILES");
+ if (catalogs == NULL) {
+ fprintf(stderr, "Variable $SGML_CATALOG_FILES not set\n");
+ } else {
+ xmlLoadCatalogs(catalogs);
+ }
#endif
#ifdef LIBXML_XINCLUDE_ENABLED
- } else if ((!strcmp(argv[i], "-xinclude")) ||
- (!strcmp(argv[i], "--xinclude"))) {
- xinclude++;
- xsltSetXIncludeDefault(1);
+ } else if ((!strcmp(argv[i], "-xinclude")) ||
+ (!strcmp(argv[i], "--xinclude"))) {
+ xinclude++;
+ xsltSetXIncludeDefault(1);
#endif
- } else if ((!strcmp(argv[i], "-param")) ||
- (!strcmp(argv[i], "--param"))) {
- i++;
- params[nbparams++] = argv[i++];
- params[nbparams++] = argv[i];
- if (nbparams >= 16) {
- fprintf(stderr, "too many params\n");
- return(1);
- }
- } else if ((!strcmp(argv[i], "-maxdepth")) ||
- (!strcmp(argv[i], "--maxdepth"))) {
- int value;
- i++;
- if (sscanf(argv[i], "%d", &value) == 1) {
- if (value > 0)
- xsltMaxDepth = value;
- }
- } else {
- fprintf(stderr, "Unknown option %s\n", argv[i]);
- usage(argv[0]);
- return(1);
- }
+ } else if ((!strcmp(argv[i], "-param")) ||
+ (!strcmp(argv[i], "--param"))) {
+ i++;
+ params[nbparams++] = argv[i++];
+ params[nbparams++] = argv[i];
+ if (nbparams >= 16) {
+ fprintf(stderr, "too many params\n");
+ return (1);
+ }
+ } else if ((!strcmp(argv[i], "-maxdepth")) ||
+ (!strcmp(argv[i], "--maxdepth"))) {
+ int value;
+
+ i++;
+ if (sscanf(argv[i], "%d", &value) == 1) {
+ if (value > 0)
+ xsltMaxDepth = value;
+ }
+ } else {
+ fprintf(stderr, "Unknown option %s\n", argv[i]);
+ usage(argv[0]);
+ return (1);
+ }
}
params[nbparams] = NULL;
xmlSubstituteEntitiesDefault(1);
- if (novalid == 0) /* TODO XML_DETECT_IDS | XML_COMPLETE_ATTRS */
- xmlLoadExtDtdDefaultValue = 6;
+ if (novalid == 0) /* TODO XML_DETECT_IDS | XML_COMPLETE_ATTRS */
+ xmlLoadExtDtdDefaultValue = 6;
else
- xmlLoadExtDtdDefaultValue = 0;
- for (i = 1; i < argc ; i++) {
- if ((!strcmp(argv[i], "-maxdepth")) ||
- (!strcmp(argv[i], "--maxdepth"))) {
- i++;
- continue;
- }
- if ((!strcmp(argv[i], "-param")) ||
- (!strcmp(argv[i], "--param"))) {
- i += 2;
+ xmlLoadExtDtdDefaultValue = 0;
+ for (i = 1; i < argc; i++) {
+ if ((!strcmp(argv[i], "-maxdepth")) ||
+ (!strcmp(argv[i], "--maxdepth"))) {
+ i++;
+ continue;
+ } else if ((!strcmp(argv[i], "-o")) ||
+ (!strcmp(argv[i], "-output")) ||
+ (!strcmp(argv[i], "--output"))) {
+ i++;
continue;
}
- if ((argv[i][0] != '-') || (strcmp(argv[i], "-") == 0)) {
- if (timing)
- gettimeofday(&begin, NULL);
- cur = xsltParseStylesheetFile((const xmlChar *)argv[i]);
- if (timing) {
- long msec;
- gettimeofday(&end, NULL);
- msec = end.tv_sec - begin.tv_sec;
- msec *= 1000;
- msec += (end.tv_usec - begin.tv_usec) / 1000;
- fprintf(stderr, "Parsing stylesheet %s took %ld ms\n",
- argv[i], msec);
- }
- if (cur != NULL) {
- if (cur->indent == 1)
- xmlIndentTreeOutput = 1;
- else
- xmlIndentTreeOutput = 0;
- i++;
- }
- break;
-
- }
+ if ((!strcmp(argv[i], "-param")) || (!strcmp(argv[i], "--param"))) {
+ i += 2;
+ continue;
+ }
+ if ((argv[i][0] != '-') || (strcmp(argv[i], "-") == 0)) {
+ if (timing)
+ gettimeofday(&begin, NULL);
+ cur = xsltParseStylesheetFile((const xmlChar *) argv[i]);
+ if (timing) {
+ long msec;
+
+ gettimeofday(&end, NULL);
+ msec = end.tv_sec - begin.tv_sec;
+ msec *= 1000;
+ msec += (end.tv_usec - begin.tv_usec) / 1000;
+ fprintf(stderr, "Parsing stylesheet %s took %ld ms\n",
+ argv[i], msec);
+ }
+ if (cur != NULL) {
+ if (cur->indent == 1)
+ xmlIndentTreeOutput = 1;
+ else
+ xmlIndentTreeOutput = 0;
+ i++;
+ }
+ break;
+
+ }
}
if ((cur != NULL) && (cur->errors == 0)) {
- for (;i < argc ; i++) {
- if (timing)
- gettimeofday(&begin, NULL);
+ for (; i < argc; i++) {
+ if (timing)
+ gettimeofday(&begin, NULL);
#ifdef LIBXML_HTML_ENABLED
- if (html)
- doc = htmlParseFile(argv[i], NULL);
- else
+ if (html)
+ doc = htmlParseFile(argv[i], NULL);
+ else
#endif
#ifdef LIBXML_DOCB_ENABLED
- if (docbook)
- doc = docbParseFile(argv[i], NULL);
- else
+ if (docbook)
+ doc = docbParseFile(argv[i], NULL);
+ else
#endif
- doc = xmlParseFile(argv[i]);
- if (doc == NULL) {
- fprintf(stderr, "unable to parse %s\n", argv[i]);
- continue;
- }
- if (timing) {
- long msec;
- gettimeofday(&end, NULL);
- msec = end.tv_sec - begin.tv_sec;
- msec *= 1000;
- msec += (end.tv_usec - begin.tv_usec) / 1000;
- fprintf(stderr, "Parsing document %s took %ld ms\n",
- argv[i], msec);
- }
+ doc = xmlParseFile(argv[i]);
+ if (doc == NULL) {
+ fprintf(stderr, "unable to parse %s\n", argv[i]);
+ continue;
+ }
+ if (timing) {
+ long msec;
+
+ gettimeofday(&end, NULL);
+ msec = end.tv_sec - begin.tv_sec;
+ msec *= 1000;
+ msec += (end.tv_usec - begin.tv_usec) / 1000;
+ fprintf(stderr, "Parsing document %s took %ld ms\n",
+ argv[i], msec);
+ }
#ifdef LIBXML_XINCLUDE_ENABLED
- if (xinclude) {
- if (timing)
- gettimeofday(&begin, NULL);
- xmlXIncludeProcess(doc);
- if (timing) {
- long msec;
- gettimeofday(&end, NULL);
- msec = end.tv_sec - begin.tv_sec;
- msec *= 1000;
- msec += (end.tv_usec - begin.tv_usec) / 1000;
- fprintf(stderr, "XInclude processing %s took %ld ms\n",
- argv[i], msec);
- }
- }
+ if (xinclude) {
+ if (timing)
+ gettimeofday(&begin, NULL);
+ xmlXIncludeProcess(doc);
+ if (timing) {
+ long msec;
+
+ gettimeofday(&end, NULL);
+ msec = end.tv_sec - begin.tv_sec;
+ msec *= 1000;
+ msec += (end.tv_usec - begin.tv_usec) / 1000;
+ fprintf(stderr, "XInclude processing %s took %ld ms\n",
+ argv[i], msec);
+ }
+ }
#endif
- if (timing)
- gettimeofday(&begin, NULL);
- if (repeat) {
- int j;
- for (j = 1;j < repeat; j++) {
- res = xsltApplyStylesheet(cur, doc, params);
- xmlFreeDoc(res);
- xmlFreeDoc(doc);
+ if (timing)
+ gettimeofday(&begin, NULL);
+ if (output == NULL) {
+ if (repeat) {
+ int j;
+
+ for (j = 1; j < repeat; j++) {
+ res = xsltApplyStylesheet(cur, doc, params);
+ xmlFreeDoc(res);
+ xmlFreeDoc(doc);
#ifdef LIBXML_HTML_ENABLED
- if (html)
- doc = htmlParseFile(argv[i], NULL);
- else
+ if (html)
+ doc = htmlParseFile(argv[i], NULL);
+ else
#endif
#ifdef LIBXML_DOCB_ENABLED
- if (docbook)
- doc = docbParseFile(argv[i], NULL);
- else
+ if (docbook)
+ doc = docbParseFile(argv[i], NULL);
+ else
#endif
- doc = xmlParseFile(argv[i]);
- }
- }
- res = xsltApplyStylesheet(cur, doc, params);
- if (timing) {
- long msec;
- gettimeofday(&end, NULL);
- msec = end.tv_sec - begin.tv_sec;
- msec *= 1000;
- msec += (end.tv_usec - begin.tv_usec) / 1000;
- if (repeat)
- fprintf(stderr,
- "Applying stylesheet %d times took %ld ms\n",
- repeat, msec);
- else
- fprintf(stderr, "Applying stylesheet took %ld ms\n",
- msec);
- }
- xmlFreeDoc(doc);
- if (res == NULL) {
- fprintf(stderr, "no result for %s\n", argv[i]);
- continue;
- }
- if (noout) {
- xmlFreeDoc(res);
- continue;
- }
+ doc = xmlParseFile(argv[i]);
+ }
+ }
+ res = xsltApplyStylesheet(cur, doc, params);
+ if (timing) {
+ long msec;
+ gettimeofday(&end, NULL);
+ msec = end.tv_sec - begin.tv_sec;
+ msec *= 1000;
+ msec += (end.tv_usec - begin.tv_usec) / 1000;
+ if (repeat)
+ fprintf(stderr,
+ "Applying stylesheet %d times took %ld ms\n",
+ repeat, msec);
+ else
+ fprintf(stderr,
+ "Applying stylesheet took %ld ms\n", msec);
+ }
+ xmlFreeDoc(doc);
+ if (res == NULL) {
+ fprintf(stderr, "no result for %s\n", argv[i]);
+ continue;
+ }
+ if (noout) {
+ xmlFreeDoc(res);
+ continue;
+ }
#ifdef LIBXML_DEBUG_ENABLED
- if (debug)
- xmlDebugDumpDocument(stdout, res);
- else {
+ if (debug)
+ xmlDebugDumpDocument(stdout, res);
+ else {
#endif
- if (cur->methodURI == NULL) {
- if (timing)
- gettimeofday(&begin, NULL);
- xsltSaveResultToFile(stdout, res, cur);
- if (timing) {
- long msec;
- gettimeofday(&end, NULL);
- msec = end.tv_sec - begin.tv_sec;
- msec *= 1000;
- msec += (end.tv_usec - begin.tv_usec) / 1000;
- fprintf(stderr, "Saving result took %ld ms\n",
- msec);
- }
- } else {
- if (xmlStrEqual(cur->method, (const xmlChar *)"xhtml")) {
- fprintf(stderr, "non standard output xhtml\n");
- if (timing)
- gettimeofday(&begin, NULL);
- xsltSaveResultToFile(stdout, res, cur);
- if (timing) {
- long msec;
- gettimeofday(&end, NULL);
- msec = end.tv_sec - begin.tv_sec;
- msec *= 1000;
- msec += (end.tv_usec - begin.tv_usec) / 1000;
- fprintf(stderr, "Saving result took %ld ms\n",
- msec);
- }
- } else {
- fprintf(stderr, "Unsupported non standard output %s\n",
- cur->method);
- }
- }
+ if (cur->methodURI == NULL) {
+ if (timing)
+ gettimeofday(&begin, NULL);
+ xsltSaveResultToFile(stdout, res, cur);
+ if (timing) {
+ long msec;
+
+ gettimeofday(&end, NULL);
+ msec = end.tv_sec - begin.tv_sec;
+ msec *= 1000;
+ msec += (end.tv_usec - begin.tv_usec) / 1000;
+ fprintf(stderr, "Saving result took %ld ms\n",
+ msec);
+ }
+ } else {
+ if (xmlStrEqual
+ (cur->method, (const xmlChar *) "xhtml")) {
+ fprintf(stderr, "non standard output xhtml\n");
+ if (timing)
+ gettimeofday(&begin, NULL);
+ xsltSaveResultToFile(stdout, res, cur);
+ if (timing) {
+ long msec;
+
+ gettimeofday(&end, NULL);
+ msec = end.tv_sec - begin.tv_sec;
+ msec *= 1000;
+ msec +=
+ (end.tv_usec - begin.tv_usec) / 1000;
+ fprintf(stderr,
+ "Saving result took %ld ms\n",
+ msec);
+ }
+ } else {
+ fprintf(stderr,
+ "Unsupported non standard output %s\n",
+ cur->method);
+ }
+ }
#ifdef LIBXML_DEBUG_ENABLED
- }
+ }
#endif
- xmlFreeDoc(res);
- }
- xsltFreeStylesheet(cur);
+ xmlFreeDoc(res);
+ } else {
+ xsltRunStylesheet(cur, doc, params, output, NULL, NULL);
+ if (timing) {
+ long msec;
+
+ gettimeofday(&end, NULL);
+ msec = end.tv_sec - begin.tv_sec;
+ msec *= 1000;
+ msec += (end.tv_usec - begin.tv_usec) / 1000;
+ fprintf(stderr,
+ "Running stylesheet and saving result took %ld ms\n",
+ msec);
+ }
+ xmlFreeDoc(doc);
+ }
+ }
+ xsltFreeStylesheet(cur);
}
xmlCleanupParser();
xmlMemoryDump();
- return(0);
+ return (0);
}
## Process this file with automake to produce Makefile.in
-all: single # Avoid doing the test in normal pass
+all: single xtchunk # Avoid doing the test in normal pass
$(top_builddir)/libxslt/xsltproc:
@(cd ../../libxslt ; make xsltproc)
echo ; \
done )
+xtchunk:
+ @(echo > .memdump)
+ @(for i in $(srcdir)/test/gdp-handbook.xml ; do \
+ echo "Texting HTML chunking on $$i :" ; \
+ html=$(srcdir)/result/html/`basename $$i .xml`.html; \
+ $(top_builddir)/libxslt/xsltproc -o $(srcdir)/result/xtchunk/html/gdp-handbook $(srcdir)/html/xtchunk.xsl $$i ; \
+ for html in $(srcdir)/result/xtchunk/html/*.html ; do \
+ orig=$(srcdir)/result/xtchunk/html/`basename $$html .html`.orig ;\
+ if [ -f $$orig ] ; then \
+ grep -v id < $$html > $$html.noid ; \
+ grep -v id < $$orig > $$orig.noid ; \
+ diff $$orig.noid $$html.noid ; \
+ rm -f $$html.noid $$orig.noid $$html; \
+ else mv $$html $$orig ; fi ; \
+ done ; \
+ grep "MORY ALLO" .memdump | grep -v "MEMORY ALLOCATED : 0" || true; \
+ rm -f $(srcdir)/result/xtchunk/html/gdp-handbook ; \
+ done )
+
#
# The full set of tests
#
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
+<html>
+<head>
+<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
+<title>A. Document Templates</title>
+<meta name="generator" content="DocBook XSL Stylesheets V1.40">
+<link rel="home" href="index.html" title="The GNOME Handbook of Writing Software Documentation">
+<link rel="up" href="index.html" title="The GNOME Handbook of Writing Software Documentation">
+<link rel="previous" href="indexs15.html" title="Resources">
+<link rel="next" href="apas17.html" title="Template 2: Applet Manual For GNOME 1.x">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<div class="navheader">
+<table width="100%" summary="Navigation header">
+<tr><th colspan="3" align="center">A. Document Templates</th></tr>
+<tr>
+<td width="20%" align="left">
+<a href="indexs15.html">Prev</a> </td>
+<th width="60%" align="center"> </th>
+<td width="20%" align="right"> <a href="apas17.html">Next</a>
+</td>
+</tr>
+</table>
+<hr>
+</div>
+<div class="appendix">
+<h2 class="title" style="clear: both">
+<a name="templates"></a>A. Document Templates</h2>
+<div class="sect1">
+<a name="template1"></a><div class="titlepage"><div><h2 class="title" style="clear: both">
+<a name="template1"></a>Template 1: Application Manual</h2></div></div>
+<p>
+ The following template should be used for all application
+ manuals. You can always get the latest copy of this
+ template from <a href="http://developer.gnome.org/projects/gdp/templates.html" target="_top">GDP
+ Documentation Templates</a>.
+ <pre class="programlisting">
+
+
+<!DOCTYPE Article PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN"[
+ <!-- if not using PNG graphic, replace reference above with
+ .....PUBLIC "-//OASIS//DTD DocBook V3.1//EN"[
+ -->
+<!ENTITY version "1.0.53">
+ <!-- replace version above with actual application version number-->
+ <!-- Template Version: 1.0.1 (do not remove this line) -->
+]>
+
+
+<!-- This is a GNOME documentation template, designed by the GNOME
+ Documentation Project Team. Please use it for writing GNOME
+ documentation, making obvious changes. In particular, all the words
+ written in UPPERCASE (with the exception of GNOME) should be
+ replaced. As for "legalnotice", please leave the reference
+ unchanged.
+
+ Remember that this is a guide, rather than a perfect model to follow
+ slavishly. Make your manual logical and readable. And don't forget
+ to remove these comments in your final documentation! ;-)
+ -->
+
+<!-- =============Document Header ============================= -->
+
+<article id="index"> <!-- please do not change the id -->
+
+ <artheader>
+ <title>MY-GNOME-APP</title>
+ <copyright>
+ <year>2000</year>
+ <holder>ME-THE-AUTHOR</holder>
+ </copyright>
+
+ <!-- translators: uncomment this:
+
+ <copyright>
+ <year>2000</year>
+ <holder>ME-THE-TRANSLATOR (Latin translation)</holder>
+ </copyright>
+
+ -->
+
+ <!-- do not put authorname in the header except in copyright - use
+ section "authors" below -->
+
+ <legalnotice>
+ <para>
+ Permission is granted to copy, distribute and/or modify this
+ document under the terms of the <citetitle>GNU Free
+ Documentation License</citetitle>, Version 1.1 or any later
+ version published by the Free Software Foundation with no
+ Invariant Sections, no Front-Cover Texts, and no Back-Cover
+ Texts. You may obtain a copy of the <citetitle>GNU Free
+ Documentation License</citetitle> from the Free Software
+ Foundation by visiting <ulink type="http"
+ url="http://www.fsf.org">their Web site</ulink> or by writing
+ to: Free Software Foundation, Inc., 59 Temple Place - Suite
+ 330, Boston, MA 02111-1307, USA.
+ </para>
+ <para>
+ Many of the names used by companies to distinguish their
+ products and services are claimed as trademarks. Where those
+ names appear in any GNOME documentation, and those trademarks
+ are made aware to the members of the GNOME Documentation
+ Project, the names have been printed in caps or initial caps.
+ </para>
+ </legalnotice>
+
+ <!-- this is the version of manual, not application -->
+ <releaseinfo>
+ This is version 1.0 of MY-GNOME-APP manual.
+ </releaseinfo>
+
+ </artheader>
+
+ <!-- ============= Document Body ============================= -->
+
+ <!-- ============= Introduction ============================== -->
+ <sect1 id="intro">
+ <title>Introduction</title>
+
+ <para>
+ <application>MY-GNOME-APP</application> is an application which
+ proves mathematical theorems. It has all the basic features
+ expected from a mathematical theorem prover, as well as a number
+ of advanced ones, such as proof by confusion. In fact, many of
+ the proofs produced by <application>MY-GNOME-APP</application>
+ are so complex that they are capable of proving almost anything
+ with a virtually null likelihood of being disproven. It also has
+ the very popular predecessor of proof by confusion, proof by
+ dialog, first implemented by Plato.
+ </para>
+ <para>
+ It also allows you to save and print theorem proofs and to add
+ comments to the proofs it produces.
+ </para>
+
+ <para>
+ To run <application>MY-GNOME-APP</application>, select
+ <menuchoice>
+ <guisubmenu>SUBMENU</guisubmenu>
+ <guimenuitem>MY-GNOME-APP</guimenuitem>
+ </menuchoice>
+ from the <guimenu>Main Menu</guimenu>, or type
+ <command>MYGNOMEAPP</command> on the command line.
+ </para>
+
+ <para>
+ <application>MY-GNOME-APP</application> is included in the
+ <filename>GNOME-PACKAGE</filename> package, which is part of the
+ GNOME desktop environment. This document describes version
+ &version; of <application>MY-GNOME-APP</application>.
+ </para>
+ </sect1>
+
+
+ <!-- ================ Usage ================================ -->
+ <!-- This section should describe basic usage of the application. -->
+
+ <sect1 id="usage">
+ <title>Using MY-GNOME-APP</title>
+ <para>
+ <application>MY-GNOME-APP</application> can be used to produce a
+ perfect proof of <emphasis>any</emphasis> mathematical theorem
+ (provided, of course, that this theorem is correct), thus
+ providing for new users an easy-to-use graphical interface to
+ modern mathematics. This section describes basic usage of
+ <application>MY-GNOME-APP</application>.
+ </para>
+
+ <!-- ========= Basic Usage =========================== -->
+ <sect2 id="mainwin">
+ <title>Basic usage</title>
+ <para>
+ Starting <application>MY-GNOME-APP</application> opens the
+ <interface>Main window</interface>, shown in <xref
+ linkend="mainwindow-fig">. The window is at first empty.
+
+ <!-- ==== Figure ==== -->
+ <figure id="mainwindow-fig">
+ <title>MY-GNOME-APP Main Window</title>
+ <screenshot>
+ <screeninfo>MY-GNOME-APP Main Window</screeninfo>
+ <graphic fileref="SCREENSHOT" format="png" srccredit="ME">
+ </graphic>
+ </screenshot>
+ </figure>
+ <!-- ==== End of Figure ==== -->
+ </para>
+
+
+ <!-- For this app, one could put "proving" or "edit" (probably even
+ both of them) as sect2's seperate from the main window
+ section. Since they were both so closely involved with the main
+ window, I decided to have them as sect3's isntead. Judgement
+ call. -->
+
+ <sect3 id="proving">
+ <title>Proving a Theorem</title>
+ <para>
+ To get a proof of a theorem, select
+ <menuchoice>
+ <guisubmenu>File</guisubmenu>
+ <guimenuitem>New</guimenuitem>
+ </menuchoice>,
+ which will
+ bring up the <interface>New Proof</interface> dialog box.
+ Enter the statement of the theorem in the
+ <guilabel>Theorem statement</guilabel> field, select your
+ desired proof type from the drop-down menu, and and press
+ <guibutton>Prove!</guibutton>.
+ </para>
+ <para>
+ If <application>MY-GNOME-APP</application> cannot prove the
+ theorem by the method you have chosen, or if you have not
+ selected a proof type at all,
+ <application>MY-GNOME-APP</application> will attempt to
+ choose the one that it thinks is most conclusive. In order,
+ it will attempt to prove the theorem with the following techniques:
+
+ <variablelist>
+ <varlistentry>
+ <term>Deduction</term>
+ <listitem>
+ <para>
+ This is a proof method that is generally accepted
+ for full credit by Logic professors.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Induction</term>
+ <listitem>
+ <para>
+ This logical style will also earn you full credit on
+ your homework.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Dialog</term>
+ <listitem>
+ <para>
+ This logical method is best for Philosophy classes,
+ and will probably only merit partial credit on Logic
+ or Mathematics homework.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Confusion</term>
+ <listitem>
+ <para>
+ Suitable only for political debates, battles of wits
+ against the unarmed, and Philosophy classes focusing
+ on the works of Kant. Use with caution.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <!-- You might want to include a note, warning, or tip, e.g. -->
+
+ <warning>
+ <title>Proving Incorrect Theorms</title>
+ <para>
+ <application>MY-GNOME-APP</application> cannot prove
+ incorrect theorems. If the theorem you have entered is not
+ demonstrably true, you will get a message to that effect
+ in the main window. To disprove a theorem, ask
+ <application>MY-GNOME-APP</application> to prove its
+ logical inverse.
+ </para>
+ </warning>
+ </sect3>
+ <sect3 id="editing">
+ <title>Editing Proofs</title>
+ <para>
+ Once you have proven the theorem, it will be displayed in
+ the <interface>main window</interface>. There, you can read
+ it over, choose text styles for different portions of it,
+ and make comments on it. This section will guide you through
+ that process.
+ </para>
+ <para>
+ To alter text styles, first select the statement you wish to
+ change by clicking on it once. You can select several
+ statements by Then, choose the style you want to apply from
+ the <guisubmenu>Style</guisubmenu> submenu of the
+ <guimenu>Edit</guimenu> menu.
+ <application>MY-GNOME-APP</application> will convert the
+ text to that style.
+ </para>
+ <para>
+ You can also enter comments on a statement by selecting that
+ statement, and then beginning to type. Comments will appear
+ after the statement you have selected.
+ </para>
+
+ <note>
+ <title>Altering The Proofs Themselves</title>
+ <para>
+ <application>MY-GNOME-APP</application> does not allow you
+ to alter a proof it has produced itself. You can, save
+ your proof as a plain text file (using the
+ <guimenuitem>Save as...</guimenuitem> menu), and alter it
+ that way. Be aware, however, that
+ <application>MY-GNOME-APP</application> uses its own file
+ format for saved proofs, and cannot re-open a file unless
+ it is in the .mga format.
+ </para>
+ </note>
+ </sect3>
+
+
+ <!-- If there are other functions performed from the main window,
+ they belong here. -->
+
+ </sect2>
+
+ <!-- =========================================================
+ Additional Sect2's should describe additional windows, such as
+ larger dialog boxes, or functionality that differs significantly
+ from the most immediate functions of the application. Make the
+ structure logical.
+ ============================================================= -->
+
+
+ <sect2 id="toolbar">
+ <title>Toolbar</title>
+ <para>
+ The toolbar (shown in <xref linkend="figure-usage-toolbar">)
+ provides access to several commonly used routines.
+ <figure id="figure-usage-toolbar">
+ <title>MY-GNOME-APP Toolbar</title>
+ <screenshot>
+ <screeninfo>MY-GNOME-APP Toolbar</screeninfo>
+ <graphic fileref="usage-toolbar.png" format="png"></graphic>
+ </screenshot>
+ </figure>
+ <variablelist>
+ <varlistentry>
+ <term>New</term>
+ <listitem>
+ <para>
+ Brings up the <interface>New Theorem</interface>
+ dialog.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Open</term>
+ <listitem>
+ <para>
+ Open an exisiting theorem you want to prove, or a
+ completed proof you wish to print or format.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Save</term>
+ <listitem>
+ <para>
+ Save the current theorem permanently in a
+ file.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </sect2>
+ <!-- ========= Menus =========================== -->
+
+ <sect2 id="menubar">
+
+ <!-- Describing the menubar ensures comprehensive feature
+ coverage. Nest itemizedlists inside variablelists so that each
+ menu is easily located by indexing software. Proper indentation
+ makes it easier! -->
+
+ <title>Menus</title>
+ <para>
+ The menu bar, located at the top of the <interface>Main
+ Window</interface>, contains the following menus:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><guimenu>File</guimenu></term>
+ <listitem>
+ <para>
+ This menu contains:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <menuchoice>
+ <shortcut>
+ <keycap>F3</keycap>
+ </shortcut>
+ <guimenuitem>Open</guimenuitem>
+ </menuchoice>
+ &mdash; This opens a file which is saved on your computer.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <menuchoice>
+ <shortcut>
+ <keycombo><keycap>Ctrl</keycap><keycap>S</keycap></keycombo>
+ </shortcut>
+ <guimenuitem>Save</guimenuitem>
+ </menuchoice>
+ &mdash; This saves your file.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <menuchoice>
+ <shortcut>
+ <keycombo><keycap>Ctrl</keycap><keycap>W</keycap></keycombo>
+ </shortcut>
+ <guimenuitem>Close</guimenuitem>
+ </menuchoice>
+ &mdash; This closes your file.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <menuchoice>
+ <shortcut>
+ <keycombo><keycap>Ctrl</keycap><keycap>Q</keycap></keycombo>
+ </shortcut>
+ <guimenuitem>Exit</guimenuitem>
+ </menuchoice>
+ &mdash; This quits the application.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><guimenu>Edit</guimenu></term>
+ <listitem>
+ <para>
+ This menu contains:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <menuchoice>
+ <shortcut>
+ <keycombo><keycap>Ctrl</keycap><keycap>X</keycap></keycombo>
+ </shortcut>
+ <guimenuitem>Cut</guimenuitem>
+ </menuchoice>
+ &mdash; This removes any text or data which is selected and
+ places it in the buffer.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <menuchoice>
+ <shortcut>
+ <keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo>
+ </shortcut>
+ <guimenuitem>Copy</guimenuitem>
+ </menuchoice>
+ &mdash; This copies any text or data which is selected into
+ the buffer.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <menuchoice>
+ <shortcut>
+ <keycombo><keycap>Ctrl</keycap><keycap>V</keycap></keycombo>
+ </shortcut>
+ <guimenuitem>Paste</guimenuitem>
+ </menuchoice>
+ &mdash; This pastes any text or data which is copied into
+ the buffer.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <guimenuitem>COMMAND1&hellip;</guimenuitem>
+ &mdash; This opens the <interface>COMMAND1</interface>
+ dialog, which is used to ....
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <guimenuitem>COMMAND2</guimenuitem>
+ &mdash; This ....
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+
+ <varlistentry>
+ <term><guimenu>Settings</guimenu></term>
+ <listitem>
+ <para>
+ This menu contains:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <guimenuitem>Preferences&hellip;</guimenuitem>
+ &mdash; This opens the <link
+ linkend="prefs"><interface>Preferences
+ Dialog</interface></link>, which allows you to configure
+ many settings.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <guimenuitem>COMMAND3</guimenuitem> &mdash;
+ This command does something.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><guimenu>Help</guimenu></term>
+ <listitem>
+ <para>
+ This menu contains:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <guimenuitem>Manual</guimenuitem> &mdash; This
+ opens the <application>GNOME Help
+ Browser</application> and displays this manual.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <guimenuitem>About</guimenuitem> &mdash; This
+ opens the <interface>About</interface> dialog
+ which shows basic information about
+ <application>MY-GNOME-APP</application>, such as
+ the author's name, the application version number,
+ and the URL for the application's Web page if one
+ exists.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+ </sect1>
+
+
+
+ <!-- ============= Customization ============================= -->
+
+ <sect1 id="prefs">
+ <title>Customization</title>
+ <para>
+ To change the application settings, select
+ <menuchoice>
+ <guimenu>Settings</guimenu>
+ <guimenuitem>Preferences...</guimenuitem>
+ </menuchoice>. This opens the
+ <interface>Preferences</interface> dialog, shown in <xref
+ linkend="preferences-fig">.
+ </para>
+
+ <figure id="preferences-fig">
+ <title>Preferences Dialog</title>
+ <screenshot>
+ <screeninfo>Preferences Dialog</screeninfo>
+ <graphic fileref="SCREENSHOT" format="png"
+ srccredit="ME">
+ </graphic>
+ </screenshot>
+ </figure>
+
+ <para>
+ The properties in the <guilabel>PREFSTABNAME</guilabel> tab are:
+
+ <!--many people use itemizedlists in cases like this. Variablelists
+ are more appropriate -->
+
+ <variablelist>
+ <varlistentry>
+ <term> <guilabel>Default Text Style</guilabel></term>
+ <listitem>
+ <para>
+ Select the default text style for statements in your
+ proof. You can still change the style for individual
+ proofs or sections of a proof at a later date.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>(Configuration Item Label)</term>
+ <listitem>
+ <para>
+ (Description of Configuration)
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>(Configuration Item Label)</term>
+ <listitem>
+ <para>
+ (Description of Configuration)
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>
+ The properties in the <guilabel>SECONDTABNAME</guilabel> tab are:
+ <variablelist>
+ <varlistentry>
+ <term>(Configuration Item Label)</term>
+ <listitem>
+ <para>
+ (Description of Configuration)
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>(Configuration Item Label)</term>
+ <listitem>
+ <para>
+ (Description of Configuration)
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>
+ After you have made all the changes you want, click on
+ <guibutton>OK</guibutton> to apply the changes and close the
+ <interface>Properties</interface> dialog. To cancel the changes
+ and return to previous values, click the
+ <guibutton>Close</guibutton> button.
+ </para>
+
+ </sect1>
+
+
+ <!-- ============= Various Sections ============================= -->
+
+ <!-- Here you should add, if necessary, several more sect1's,
+ describing other windows (besides the main one), file formats,
+ preferences dialogs, etc. as appropriate. Try not to make any of
+ these sections too long. -->
+
+
+ <!-- ============= Bugs ================================== -->
+ <!-- This section should describe known bugs and limitations of
+ the program if there are any - please be frank and list all
+ problems you know of. -->
+ <sect1 id="bugs">
+ <title>Known Bugs and Limitations</title>
+ <para>
+ This application has no known bugs.
+ </para>
+ </sect1>
+
+
+<!-- ============= Authors ================================ -->
+
+ <sect1 id="authors">
+ <title>Authors</title>
+ <para>
+ <application>MY-GNOME-APP</application> was written by GNOME-HACKER
+ (<email>hacker@gnome.org</email>). To find more information about
+ <application>MY-GNOME-APP</application>, please visit the <ulink
+ url="http://www.my-gnome-app.org" type="http">MY-GNOME-APP Web
+ page</ulink>. Please send all comments, suggestions, and bug
+ reports to the <ulink url="http://bugs.gnome.org" type="http">GNOME
+ bug tracking database</ulink>. (Instructions for submitting bug
+ reports can be found <ulink
+ url="http://bugs.gnome.org/Reporting.html" type="http">
+ on-line</ulink>.) You can also use <application>Bug Report
+ Tool</application> (<command>bug-buddy</command>), available in the
+ <guisubmenu>Utilities</guisubmenu> submenu of <guimenu>Main
+ Menu</guimenu>, for submitting bug reports.
+ </para>
+
+ <para>
+ This manual was written by ME
+ (<email>MYNAME@MYADDRESS</email>). Please send all comments and
+ suggestions regarding this manual to the <ulink type="http"
+ url="http://developer.gnome.org/projects/gdp">GNOME Documentation
+ Project</ulink> by sending an email to
+ <email>docs@gnome.org</email>. You can also add your comments online
+ by using the <ulink type="http"
+ url="http://www.gnome.org/gdp/doctable/">GNOME Documentation Status
+ Table</ulink>.
+ </para>
+
+ <!-- For translations: uncomment this:
+
+ <para>
+ Latin translation was done by ME
+ (<email>MYNAME@MYADDRESS</email>). Please send all comments and
+ suggestions regarding this translation to SOMEWHERE.
+ </para>
+
+ -->
+
+ </sect1>
+
+
+ <!-- ============= Application License ============================= -->
+
+ <sect1 id="license">
+ <title>License</title>
+ <para>
+ This program is free software; you can redistribute it and/or
+ modify it under the terms of the <citetitle>GNU General Public
+ License</citetitle> as published by the Free Software Foundation;
+ either version 2 of the License, or (at your option) any later
+ version.
+ </para>
+ <para>
+ This program is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ <citetitle>GNU General Public License</citetitle> for more details.
+ </para>
+ <para>
+ A copy of the <citetitle>GNU General Public License</citetitle> is
+ included as an appendix to the <citetitle>GNOME Users
+ Guide</citetitle>. You may also obtain a copy of the
+ <citetitle>GNU General Public License</citetitle> from the Free
+ Software Foundation by visiting <ulink type="http"
+ url="http://www.fsf.org">their Web site</ulink> or by writing to
+ <address>
+ Free Software Foundation, Inc.
+ <street>59 Temple Place</street> - Suite 330
+ <city>Boston</city>, <state>MA</state> <postcode>02111-1307</postcode>
+ <country>USA</country>
+ </address>
+ </para>
+ </sect1>
+</article>
+
+
+
+
+
+
+
+
+
+
+
+
+</pre>
+ </p>
+</div>
+</div>
+<div class="navfooter">
+<hr>
+<table width="100%" summary="Navigation footer">
+<tr>
+<td width="40%" align="left">
+<a href="indexs15.html">Prev</a> </td>
+<td width="20%" align="center"><a href="index.html">Home</a></td>
+<td width="40%" align="right"> <a href="apas17.html">Next</a>
+</td>
+</tr>
+<tr>
+<td width="40%" align="left">Resources </td>
+<td width="20%" align="center"><a href="index.html">Up</a></td>
+<td width="40%" align="right"> Template 2: Applet Manual For GNOME 1.x</td>
+</tr>
+</table>
+</div>
+</body>
+</html>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
+<html>
+<head>
+<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
+<title>Template 2: Applet Manual For GNOME 1.x</title>
+<meta name="generator" content="DocBook XSL Stylesheets V1.40">
+<link rel="home" href="index.html" title="The GNOME Handbook of Writing Software Documentation">
+<link rel="up" href="apa.html" title="A. Document Templates">
+<link rel="previous" href="apa.html" title="A. Document Templates">
+<link rel="next" href="apas18.html" title="Template 2: Applet Manual For GNOME 2.x">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<div class="navheader">
+<table width="100%" summary="Navigation header">
+<tr><th colspan="3" align="center">Template 2: Applet Manual For GNOME 1.x</th></tr>
+<tr>
+<td width="20%" align="left">
+<a href="apa.html">Prev</a> </td>
+<th width="60%" align="center">A. Document Templates</th>
+<td width="20%" align="right"> <a href="apas18.html">Next</a>
+</td>
+</tr>
+</table>
+<hr>
+</div>
+<div class="sect1">
+<a name="template2-1x"></a><div class="titlepage"><div><h2 class="title" style="clear: both">
+<a name="template2-1x"></a>Template 2: Applet Manual For GNOME 1.x</h2></div></div>
+<p>
+ The following templates should be used for all applet
+ manuals in GNOME 1.x releases. You can always get the latest
+ copy of these templates from <a href="http://developer.gnome.org/projects/gdp/templates.html" target="_top">GDP
+ Documentation Templates</a>. Note that the template
+ consists of two files; the first file calls the second as an
+ entity. You should name the first file
+ <tt><i><tt>appletname</tt></i>-applet.sgml</tt>
+ and the second file should be named
+ <tt><i><tt>appletname</tt></i>.sgml</tt>,
+ where
+ <tt><i><tt>appletname</tt></i></tt> is
+ the name of the applet.
+ <pre class="programlisting">
+
+
+<!DOCTYPE Article PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN"[
+ <!entity APPLETNAME.sgml SYSTEM "applet_template_1.sgml">
+ <!-- Template Version: 1.0.1 (do not remove this line) -->
+]>
+
+<!-- This is a GNOME documentation template, designed by the GNOME
+ Documentation Project Team. Please use it for writing GNOME
+ documentation, making obvious changes. In particular, all the words
+ written in UPPERCASE (with the exception of GNOME) should be
+ replaced. As for "legalnotice", please leave the reference
+ unchanged,make sure to add/remove trademarks to the list as
+ appropriate for your document.
+
+ Please don't forget to remove these comments in your final documentation,
+ thanks ;-).
+-->
+
+<article id="index"> <!-- please do not change the id -->
+
+ <!-- ============= Document Header ============================= -->
+ <artheader>
+ <title>APPLETNAME Applet</title>
+ <copyright>
+ <year>2000</year>
+ <holder>YOURFULLNAME</holder>
+ </copyright>
+
+ <!-- translators: uncomment this:
+
+ <copyright>
+ <year>2000</year>
+ <holder>ME-THE-TRANSLATOR (Latin translation)</holder>
+ </copyright>
+
+ -->
+
+ <!-- do not put authorname in the header except in copyright - use
+ section "authors" below -->
+
+ <legalnotice>
+ <para>
+ Permission is granted to copy, distribute and/or modify this
+ document under the terms of the <citetitle>GNU Free Documentation
+ License</citetitle>, Version 1.1 or any later version published
+ by the Free Software Foundation with no Invariant Sections, no
+ Front-Cover Texts, and no Back-Cover Texts. You may obtain a copy
+ of the <citetitle>GNU Free Documentation License</citetitle> from
+ the Free Software Foundation by visiting <ulink type="http"
+ url="http://www.fsf.org">their Web site</ulink> or by writing to:
+ Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+ Boston, MA 02111-1307, USA.
+ </para>
+ <para>
+ Many of the names used by companies to distinguish their products and
+ services are claimed as trademarks. Where those names appear in any
+ GNOME documentation, and those trademarks are made aware to the members
+ of the GNOME Documentation Project, the names have been printed in caps
+ or initial caps.
+ </para>
+ </legalnotice>
+
+ <releaseinfo>
+ This is version XXX of the APPLETNAME applet manual.
+ </releaseinfo>
+ </artheader>
+
+ <!-- ============= Document Body ============================= -->
+
+ &APPLETNAME.sgml;
+
+</article>
+
+
+
+
+
+</pre>
+ <pre class="programlisting">
+
+ <!-- Template Version: 1.0.1 (do not remove this line) -->
+
+ <sect1 id="APPLET">
+ <title>APPLET Applet</title>
+
+ <para>
+ <application>APPLET</application> applet, shown in <xref
+ linkend="APPLETapplet-fig">, allows you to &hellip;. To add this
+ applet to a <interface>Panel</interface>,
+ right-click on the <interface>Panel</interface> and choose
+ <menuchoice>
+ <guimenu>Panel</guimenu>
+ <guisubmenu>Add to panel</guisubmenu>
+ <guisubmenu>Applet</guisubmenu>
+ <guisubmenu>SECTION</guisubmenu>
+ <guimenuitem>APPLET</guimenuitem>
+ </menuchoice>.
+ </para>
+
+ <figure id="APPLETapplet-fig">
+ <title>APPLET Applet</title>
+ <screenshot>
+ <screeninfo>APPLET Applet</screeninfo>
+ <graphic format="png" fileref="APPLET_applet"
+ srccredit="YOURNAME">
+ </graphic>
+ </screenshot>
+ </figure>
+
+ <!-- ============= Usage ================================ -->
+ <sect2 id="APPLET-usage">
+ <title>Usage</title>
+ <para>
+ (Place a short description of how to use the applet here.)
+ </para>
+
+ <para>
+ Right-clicking on the applet brings up a menu containing the
+ following items:
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ <guimenuitem>Properties&hellip;</guimenuitem> &mdash;
+ opens the <link linkend="APPLET-prefs">
+ <guilabel>Properties</guilabel></link> dialog.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <guimenuitem>Help</guimenuitem> &mdash;
+ displays this document.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <guimenuitem>About&hellip;</guimenuitem> &mdash;
+ shows basic information about <application>APPLET
+ Applet</application>, including the applet's version and the
+ author's name.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </para>
+ </sect2>
+
+
+ <!-- ============= Customization ============================= -->
+ <sect2 id="APPLET-prefs">
+ <title>Customization</title>
+ <para>
+ You can customize <application>APPLET</application>
+ applet by right-clicking on it and choosing
+ <guimenuitem>Properties&hellip;</guimenuitem>. This will open the
+ <interface>Properties</interface> dialog(shown in <xref
+ linkend="APPLET-settings-fig">), which allows you to
+ change various settings.
+ </para>
+
+ <figure id="APPLET-settings-fig">
+ <title>Properties dialog</title>
+ <screenshot>
+ <screeninfo>Properties dialog</screeninfo>
+ <graphic format="png" fileref="APPLET_settings"
+ srccredit="YOURNAME">
+ </graphic>
+ </screenshot>
+ </figure>
+
+ <para>
+ The properties are:
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ (Configuration Item Label) &mdash; If this button is
+ checked&hellip;(description)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ (Configuration Item Label) &mdash; Selecting this
+ button&hellip;(description)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ (Configuration Item Label) &mdash; Enter the name of
+ &hellip;(description)
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ After you have made all the changes you want, click on
+ <guibutton>OK</guibutton> to apply the changes and close the
+ <interface>Properties</interface> dialog. To cancel the changes
+ and return to previous values, click the
+ <guibutton>Close</guibutton> button.
+ </para>
+ </sect2>
+
+
+ <!-- ============= Bugs ================================== -->
+ <!-- This section should describe known bugs and limitations of
+ the program if there are any - please be frank and list all
+ problems you know of -->
+ <sect2 id="bugs">
+ <title>Known Bugs and Limitations</title>
+ <para>
+ This applet has no known bugs.
+ </para>
+ </sect2>
+
+
+ <!-- ============= Authors ================================ -->
+
+ <sect2 id="authors">
+ <title>Authors</title>
+ <para>
+ <application>APPLET</application> was written by GNOME-HACKER
+ (<email>hacker@gnome.org</email>). Please send all comments,
+ suggestions, and bug
+ reports to the <ulink url="http://bugs.gnome.org" type="http">GNOME
+ bug tracking database</ulink>. (Instructions for submitting bug
+ reports can be found <ulink
+ url="http://bugs.gnome.org/Reporting.html" type="http">
+ on-line</ulink>. You can also use <application>Bug Report
+ Tool</application> (<command>bug-buddy</command>), available in the
+ <guisubmenu>Utilities</guisubmenu> submenu of <guimenu>Main
+ Menu</guimenu>, for submitting bug reports.
+ </para>
+
+ <para>
+ This manual was written by ME
+ (<email>MYNAME@MYADDRESS</email>). Please send all comments and
+ suggestions regarding this manual to the <ulink type="http"
+ url="http://developer.gnome.org/projects/gdp">GNOME Documentation
+ Project</ulink> by sending an email to
+ <email>docs@gnome.org</email>. You can also submit comments online
+ by using the <ulink type="http"
+ url="http://www.gnome.org/gdp/doctable/">GNOME Documentation
+ Status Table</ulink>.
+ </para>
+
+ <!-- For translations: uncomment this:
+
+ <para>
+ Latin translation was done by ME
+ (<email>MYNAME@MYADDRESS</email>). Please send all comments and
+ suggestions regarding this translation to SOMEWHERE.
+ </para>
+
+ -->
+
+ </sect2>
+
+
+ <!-- ============= Application License ============================= -->
+
+ <sect2 id="license">
+ <title>License</title>
+ <para>
+ This program is free software; you can redistribute it and/or
+ modify it under the terms of the <citetitle>GNU General Public
+ License</citetitle> as published by the Free Software Foundation;
+ either version 2 of the License, or (at your option) any later
+ version.
+ </para>
+ <para>
+ This program is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ <citetitle>GNU General Public License</citetitle> for more details.
+ </para>
+ <para>
+ A copy of the <citetitle>GNU General Public License</citetitle> is
+ included as an appendix to the <citetitle>GNOME Users
+ Guide</citetitle>. You may also obtain a copy of the
+ <citetitle>GNU General Public License</citetitle> from the Free
+ Software Foundation by visiting <ulink type="http"
+ url="http://www.fsf.org">their Web site</ulink> or by writing to
+ <address>
+ Free Software Foundation, Inc.
+ <street>59 Temple Place</street> - Suite 330
+ <city>Boston</city>, <state>MA</state> <postcode>02111-1307</postcode>
+ <country>USA</country>
+ </address>
+ </para>
+ </sect2>
+
+ </sect1>
+
+
+
+
+
+
+
+
+</pre>
+ </p>
+</div>
+<div class="navfooter">
+<hr>
+<table width="100%" summary="Navigation footer">
+<tr>
+<td width="40%" align="left">
+<a href="apa.html">Prev</a> </td>
+<td width="20%" align="center"><a href="index.html">Home</a></td>
+<td width="40%" align="right"> <a href="apas18.html">Next</a>
+</td>
+</tr>
+<tr>
+<td width="40%" align="left">A. Document Templates </td>
+<td width="20%" align="center"><a href="apa.html">Up</a></td>
+<td width="40%" align="right"> Template 2: Applet Manual For GNOME 2.x</td>
+</tr>
+</table>
+</div>
+</body>
+</html>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
+<html>
+<head>
+<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
+<title>Template 2: Applet Manual For GNOME 2.x</title>
+<meta name="generator" content="DocBook XSL Stylesheets V1.40">
+<link rel="home" href="index.html" title="The GNOME Handbook of Writing Software Documentation">
+<link rel="up" href="apa.html" title="A. Document Templates">
+<link rel="previous" href="apas17.html" title="Template 2: Applet Manual For GNOME 1.x">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<div class="navheader">
+<table width="100%" summary="Navigation header">
+<tr><th colspan="3" align="center">Template 2: Applet Manual For GNOME 2.x</th></tr>
+<tr>
+<td width="20%" align="left">
+<a href="apas17.html">Prev</a> </td>
+<th width="60%" align="center">A. Document Templates</th>
+<td width="20%" align="right"> </td>
+</tr>
+</table>
+<hr>
+</div>
+<div class="sect1">
+<a name="template2-2x"></a><div class="titlepage"><div><h2 class="title" style="clear: both">
+<a name="template2-2x"></a>Template 2: Applet Manual For GNOME 2.x</h2></div></div>
+<p>
+ The following templates should be used for all applet
+ manuals in GNOME 2.x releases. You can always get the latest
+ copy of these templates from <a href="http://developer.gnome.org/projects/gdp/templates.html" target="_top">GDP
+ Documentation Templates</a>.
+ </p>
+<p>
+ Note that this template consists of two files. The first file
+ is an introductory chapter. You should not modify this
+ chapter. The second file is the actual applet document, which
+ you should modify to describe the applet you are documenting.
+ You can name the first file whatever you like, such as
+ <tt>gnome-applets.sgml</tt>. Name the second file
+ according to the applet's name:
+ <tt><i><tt>appletname</tt></i>-applet.sgml</tt>.
+ Make sure you update the entity
+ at the top of the shell document to reflect the new name of
+ the applet document.
+ </p>
+<p>
+ <pre class="programlisting">
+
+<!DOCTYPE book PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN"[
+<!ENTITY TEMPLATE-APPLET SYSTEM "gnome-applet-template.sgml.part">
+
+]>
+
+<book id="gnome-applets">
+
+ <bookinfo>
+ <title>GNOME Applets</title>
+ <authorgroup>
+ <author><firstname>Telsa</firstname><surname>Gwynne</surname></author>
+ <author><firstname>John</firstname><surname>Fleck</surname></author>
+ <author><firstname>David</firstname><surname>Mason</surname>
+ <affiliation><orgname>Red Hat, Inc.</orgname></affiliation>
+ </author>
+ <author><firstname>Dan</firstname><surname>Mueth</surname></author>
+ <author><firstname>Alexander</firstname><surname>Kirillov</surname></author>
+ </authorgroup>
+ <edition>GNOME Applets version 0.1 for GNOME 1.1.5</edition>
+ <pubdate>2000</pubdate>
+ <copyright>
+ <year>2000</year>
+ <holder>Telsa Gwynne, John Fleck, Red Hat Inc., Dan Mueth, and
+ Alexander Kirillov</holder>
+ </copyright>
+ <legalnotice>
+ <para>
+ Permission is granted to make and distribute verbatim copies of this
+ manual provided the copyright notice and this permission notice are
+ preserved on all copies.
+ </para>
+ <para>
+ Permission is granted to copy and distribute modified versions of
+ this manual under the conditions for verbatim copying, provided that
+ the entire resulting derived work is distributed under the terms of a
+ permission notice identical to this one.
+ </para>
+ <para>
+ Permission is granted to copy and distribute translations of this
+ manual into another language, under the above conditions for modified
+ versions, except that this permission notice may be stated in a
+ translation approved by the Free Software Foundation.
+ </para>
+ <para>
+ Many of the names used by companies to distinguish their products and
+ services are claimed as trademarks. Where those names appear in any
+ GNOME documentation, and those trademarks are made aware to the members
+ of the GNOME Documentation Project, the names have been printed in caps
+ or initial caps.
+ </para>
+ </legalnotice>
+ </bookinfo>
+
+ <!-- #### Introduction ###### -->
+ <chapter id="applets-intro">
+ <title>Introduction</title>
+
+ <!-- #### Intro | What Are Applets? ###### -->
+ <sect1 id="applets-what-are">
+ <title>What Are Applets?</title>
+ <para>
+ Applets are one of the most popular and useful objects you can add
+ to your <interface>Panel</interface> to customize your desktop.
+ An applet is a small application which runs inside a small area of
+ your <interface>Panel</interface>. Applets have been written for
+ a wide range of purposes. Some are very powerful interactive
+ tools, such as the <application>Tasklist</application> Applet
+ which allows you to easily
+ control all of your main applications. Others are simple system
+ monitors, displaying information such as the amount of power left
+ in the battery on your laptop (see <application>Battery Charge
+ Monitor</application>) or weather
+ information(see <application>GNOME Weather</application>). Some
+ are simply for amusement(see <application>Fish</application>).
+ </para>
+
+ <para>
+ Applets are similar to swallowed applications in that both of them
+ reside within the <interface>Panel</interface>. However,
+ swallowed applications are generally applications which were
+ not designed to run within the <interface>Panel</interface>.
+ Typically one will swallow an application which already exists in
+ the main <interface>desktop</interface> area, putting it into your
+ <interface>Panel</interface>. The application will continue to
+ run in the <interface>Panel</interface> until you end the
+ application or unswallow it, placing it back onto the main part of
+ your desktop when you need to.
+ </para>
+
+ <para>
+ <figure id="example-applets-fig">
+ <title>Example Applets</title>
+ <screenshot>
+ <screeninfo>Example Applets</screeninfo>
+ <graphic fileref="example_applets" format="png"
+ srccredit="muet">
+ </graphic>
+ </screenshot>
+ </figure>
+ Several example applets are shown in <xref
+ linkend="example-applets-fig">. From left to right, they are: (1)
+ <application>Mixer Applet</application>, which allows you to turn
+ on/off sound and control its volume by clicking on the applet. (2)
+ <application>Sound Monitor</application> Applet, which displays
+ the current volume of sound being played and allows you to control
+ various sound features. (3) <application>GTCD</application>
+ Applet, a CD player which has all its controls
+ available in the applet and displays the track and time. (4)
+ <application>Drive Mount</application> Applet, used to mount and
+ unmount drives with a single click of the mouse. (5)
+ <application>Desk Guide</application> which allows you to view
+ and control multiple virtual screens. (6)
+ <application>Tasklist</application> Applet which allows you to
+ control your various windows and applications.
+ </para>
+ <para>
+ There are many other applets to choose from. The rest of this
+ chapter will explain the basic information to get you started
+ adding, moving, and removing applets from your
+ <interface>Panels</interface> and using them. The following
+ chapters go through each of the standard GNOME applets describing
+ them in detail. There are also additional applets which can be
+ downloaded off the Web. See <ulink type="http"
+ url="http://www.gnome.org/applist/list-martin.phtml">The GNOME
+ Software Map</ulink> for lists of additional GNOME applications
+ and applets.
+ </para>
+ <para>
+ As you read through the the rest of this chapter, you should try
+ adding and removing applets from your <interface>Panel</interface> and
+ experiment with them freely.
+ </para>
+ </sect1>
+
+ <!-- #### Intro | Adding, Moving, and Removing Applets ###### -->
+ <sect1 id="applet-add-move-replace">
+ <title>Adding, Moving, and Removing Applets</title>
+
+ <sect2 id="adding-applets">
+ <title>Adding Applets to a Panel</title>
+ <para>
+ To add an applet to a <interface>Panel</interface>, right-click
+ on the <interface>Panel</interface> and select
+ <menuchoice><guimenu>Panel</guimenu><guisubmenu>Add to panel</guisubmenu>
+ <guisubmenu>Applet</guisubmenu></menuchoice>. This will show you
+ the menu of all the applets on your system, divided into
+ categories. Choosing any applet from this menu will add it to the
+ <interface>Panel</interface>.
+ </para>
+ </sect2>
+
+ <sect2 id="moving-applets">
+ <title>Moving Applets In or Between Panels</title>
+ <para>
+ It is easy to move applets in a <interface>Panel</interface> or
+ between two <interface>Panels</interface>. If you have a
+ three-button mouse, just move the mouse over the applet, depress
+ the middle mouse button and drag the applet to its new location,
+ releasing the middle mouse button when you are finished. Note
+ that you can drag applets within a <interface>Panel</interface>
+ or between two <interface>Panels</interface> this way. If you
+ don't have a three-button mouse, just
+ right-click on the applet and choose
+ <guimenuitem>Move</guimenuitem>. The cursor will turn into a
+ cross and the applet will move with your mouse until you press
+ any mouse button to indicate you are finished moving it.
+ If, in the course of this movement, it hits
+ other objects, the behavior depends on the global preferences
+ you have set for your <interface>Panels</interface> in the
+ <application>GNOME Control Center</application>: the applet you are
+ moving can switch places with other objects, "push" all objects
+ it meets, or "jump" over all other objects without disturbing
+ them. You can also override the default behavior by holding
+ <keycap>Shift</keycap> button (for "push" mode),
+ <keycap>Ctrl</keycap> (for "switched" mode), or
+ <keycap>Alt</keycap> (for "free" mode, i.e. jumping other other
+ objects without disturbing them) button while dragging.
+ </para>
+ <para>
+ To change the global Panel preferences, right-click on any applet
+ or <interface>Panel</interface> and select
+ <menuchoice>
+ <guimenu>Panel</guimenu>
+ <guimenuitem>Global Preferences...</guimenuitem>
+ </menuchoice>.
+ The <guilabel>Default movement mode</guilabel> is set under the
+ <guilabel>Applets</guilabel> tab.
+ </para>
+ </sect2>
+
+ <sect2 id="removing-applets">
+ <title>Removing Applets from a Panel</title>
+ <para>
+ To remove an applet from a <interface>Panel</interface>,
+ right-click on the applet and select <guimenuitem>Remove from
+ panel...</guimenuitem>.
+ </para>
+ </sect2>
+ </sect1>
+
+
+ <!-- #### Intro | The Right-Click Pop-Up Menu ###### -->
+ <sect1 id="right-click-pop-up-menu">
+ <title>The Right-Click Pop-Up Menu</title>
+ <para>
+ Clicking the right mouse button on any applet brings up
+ a <guimenu>pop-up menu</guimenu>. This
+ menu always has certain standard menu items in it and
+ often has additional items which vary depending on the particular
+ applet.
+ </para>
+ <sect2 id="standard-right-click-items">
+ <title>Standard Pop-Up Items</title>
+ <para>
+ All applets should have the following items in their right-click
+ <guimenu>pop-up menu</guimenu>:
+ <variablelist>
+ <varlistentry>
+ <term>Remove from panel</term>
+ <listitem>
+ <para>
+ The <guimenuitem>Remove from panel</guimenuitem> menu item
+ removes the applet from the <interface>Panel</interface>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Move</term>
+ <listitem>
+ <para>
+ After selecting <guimenuitem>Move</guimenuitem>, your mouse
+ pointer will change appearance (typically to a cross with
+ arrows in each direction). As you move your mouse, the applet
+ will move with it. When you have finished moving the applet,
+ click any mouse button and the applet will anchor in its
+ current position. Note that applets can be moved between two
+ <interface>Panels</interface> this way.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Panel</term>
+ <listitem>
+ <para>
+ The <guisubmenu>Panel</guisubmenu> submenu contains various
+ items and submenus for adding and removing
+ <interface>Panels</interface> and applets and for changing
+ the configuration.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>About</term>
+ <listitem>
+ <para>
+ The <guimenuitem>About...</guimenuitem> menu item brings up a
+ dialogue box containing various information about the applet,
+ typically including the applet's name, version, author,
+ copyright, license and desciption.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Help</term>
+ <listitem>
+ <para>
+ The <guimenuitem>Help</guimenuitem> menu item brings up the help
+ manual for the applet.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </sect2>
+
+ <sect2 id="applet-properties-dialog">
+ <title>The Applet Properties Dialog</title>
+ <para>
+ Many applets have customizable properties. These applets will
+ have a <guimenuitem>Properties...</guimenuitem> menu item in their
+ right-click <guimenu>pop-up menu</guimenu> which brings up the
+ <interface>Properties</interface> dialog where you can alter the
+ appearance or behaviour of the applet.
+ <figure id="example-props-dialog-fig">
+ <title>An Example Applet Properties Dialog</title>
+ <screenshot>
+ <screeninfo>An Example Applets Properties Dialog</screeninfo>
+ <graphic fileref="applet_props_dialog" format="png"
+ srccredit="muet">
+ </graphic>
+ </screenshot>
+ </figure>
+ All <interface>Properties</interface> dialogs have the following
+ buttons at the bottom of the dialog:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <guibutton>OK</guibutton> &mdash;
+ Pressing <guibutton>OK</guibutton> will activate any changes
+ in the properties you have made and close the
+ <interface>Properties</interface> dialog.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <guibutton>Apply</guibutton> &mdash;
+ Pressing <guibutton>Apply</guibutton> at any time will
+ make your changes active without closing the
+ <interface>Properties</interface> dialog. This is helpful if
+ you would like to test the effects of the changes you have
+ made but may want to continue changing the properties.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <guibutton>Close</guibutton> &mdash;
+ Pressing <guibutton>Close</guibutton> will close the
+ <interface>Properties</interface> dialog. Only changes in the
+ configuration which were previously applied with the
+ <guibutton>Apply</guibutton> button will persist. Other
+ changes will not be made active.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <guibutton>Help</guibutton> &mdash;
+ Pressing <guibutton>Help</guibutton> brings up the manual for
+ the application, opening it to the page describing the
+ <interface>Properties</interface> dialog.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect2>
+
+ <sect2 id="common-right-click-items">
+ <title>Other Common Pop-Up Items</title>
+ <para>
+ Many applets also have one or more of the following items in their
+ right-click pop-up menu:
+ <variablelist>
+ <varlistentry>
+ <term>Run...</term>
+ <listitem>
+ <para>
+ The <guimenuitem>Run...</guimenuitem> menu item generally
+ invokes a program which is related to the applet in some way
+ but which runs in its own window rather than in the
+ panel. For example:
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+ The <application>CPU Load</application> applet, which monitors
+ what programs are running, has a <guimenuitem>Run
+ gtop...</guimenuitem> menu item. Selecting this menu item
+ starts <application>GTop</application>, which allows you to
+ view and control programs which are running.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <application>CD Player</application> applet has a
+ <guimenuitem>Run gtcd...</guimenuitem> menu item which
+ starts the GNOME <application>CD Player</application> when
+ selected, which has more capabilities than the applet.
+ </para>
+ </listitem>
+ </orderedlist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </sect2>
+ </sect1>
+
+ <sect1 id="feedback">
+ <title>Feedback</title>
+ <sect2 id="reporting-bugs">
+ <title>Reporting Applet Bugs</title>
+ <para>
+ GNOME users are encouraged to report bugs to <ulink type="http"
+ url="http://bugs.gnome.org">The GNOME Bug Tracking
+ System</ulink>. The easiest way to submit bugs is to use the
+ <application>Bug Report Tool</application> program by selecting
+ <menuchoice>
+ <guimenu>Main Menu</guimenu> <guisubmenu>Utilities</guisubmenu>
+ <guimenuitem>Bug Report Tool</guimenuitem>
+ </menuchoice>.
+ Be sure to be complete in describing what you did to cause the
+ bug to surface and, if possible, describe how the developer can
+ reproduce the the scenario.
+ </para>
+ </sect2>
+ <sect2 id="documentation-feedback">
+ <title>Providing Feedback</title>
+ <para>
+ GNOME users are welcome to provide suggestions for how
+ applications and documentation can be improved. Suggestions for
+ application changes should be submitted using the
+ <application>Bug Report Tool</application> discussed above.
+ Suggestions for documentation changes can be emailed directly to
+ the documentation author (whose email should be included in the
+ "Authors" section of the document) or by sending an email to
+ <email>docs@gnome.org</email>.
+ </para>
+ </sect2>
+ <sect2 id="joining-gnome">
+ <title>Joining GNOME</title>
+ <para>
+ GNOME is a community project, created by hundreds of programmers,
+ documentation writers, icon design artists, web masters, and
+ other people, most of whom work on a volunteer basis. New GNOME
+ contributors are always welcome. To join the GNOME team, visit
+ these web sites: developers &mdash; <ulink type="http"
+ url="http://developer.gnome.org">The GNOME Development
+ Site</ulink>, documentation writers &mdash; <ulink type="http"
+ url="http://developer.gnome.org/projects/gdp">The GNOME Documentation
+ Project</ulink>, icon design artists &mdash; <ulink type="http"
+ url="http://gnome-icons.sourceforge.net/">Gnome Icon Web</ulink>,
+ general &mdash; <ulink type="http"
+ url="http://developer.gnome.org/helping/">Helping GNOME</ulink>,
+ or just join the gnome-list email list (see <ulink type="http"
+ url="http://www.gnome.org/resources/mailing-lists.html">GNOME Mailing
+ Lists</ulink>) to discuss what you are interested in doing.
+ </para>
+ </sect2>
+ </sect1>
+ </chapter>
+
+ <!-- ############### Template Applets ##################### -->
+ <chapter id="template-applets">
+ <title>Template Applets</title>
+
+ &TEMPLATE-APPLET
+
+ </chapter>
+
+</book>
+
+
+
+
+
+
+
+
+ </pre>
+
+ <pre class="programlisting">
+
+
+ <!-- Please replace everywhere below GNOMEAPPLET with the name of -->
+ <!-- your applet. Most importantly, all id attributes should start -->
+ <!-- with the name of your applet - this is necessary to avoid name -->
+ <!-- conflict among different applets -->
+ <!-- Please replace YOUR-NAME with your name and YOUR-EMAIL with your email-->
+ <!-- Please replace HACKER-NAME with the applet author's name and -->
+ <!-- HACKER-EMAIL with the applet author's email -->
+
+ <!-- You should name your file: GNOMEAPPLET-applet.sgml -->
+ <!-- Screenshots should be in PNG format and placed in the -->
+ <!-- same directory as GNOMEAPPLET-applet.sgml -->
+
+ <!-- Applet docs will be merged into <chapter>'s inside a -->
+ <!-- <book>. Thus, the indentation below (2 spaces before the <sect1>) is -->
+ <!-- correct.-->
+
+ <!-- Permission is granted to make and distribute verbatim copies of -->
+ <!-- this manual provided the copyright notice and this permission -->
+ <!-- notice are preserved on all copies. -->
+ <!-- -->
+ <!-- Permission is granted to copy and distribute modified versions of -->
+ <!-- this manual under the conditions for verbatim copying, provided -->
+ <!-- that the entire resulting derived work is distributed under the -->
+ <!-- terms of a permission notice identical to this one. -->
+ <!-- -->
+ <!-- Permission is granted to copy and distribute translations of this -->
+ <!-- manual into another language, under the above conditions for -->
+ <!-- modified versions, except that this permission notice may be -->
+ <!-- stated in a translation approved by the Foundation. -->
+
+ <!-- ############### GNOMEAPPLET ############### -->
+ <sect1 id="GNOMEAPPLET">
+ <title>GNOMEAPPLET Applet</title>
+
+ <para>
+ <application>GNOMEAPPLET</application> applet, shown in <xref
+ linkend="GNOMEAPPLET-fig">, does this and that. To learn how to
+ add this applet to a <interface>Panel</interface>, see <xref
+ linkend="adding-applets">.
+ </para>
+
+
+ <figure id="GNOMEAPPLET-fig">
+ <title>GNOMEAPPLET</title>
+ <screenshot>
+ <screeninfo>GNOMEAPPLET</screeninfo>
+ <graphic format="png" fileref="GNOMEAPPLET-fig" srccredit="ME">
+ </graphic>
+ </screenshot>
+ </figure>
+
+ <sect2 id="GNOMEAPPLET-usage">
+ <title>Usage</title>
+ <para>
+ This applet does nothing. To use it, just
+ left-click on it and it will instantly do nothing.
+ </para>
+ </sect2>
+
+ <sect2 id="GNOMEAPPLET-right-click">
+ <title>Right-Click Pop-Up Menu Items</title>
+ <para>
+ In addition to the standard menu items (see <xref
+ linkend="standard-right-click-items">), the right-click pop-up menu has
+ the following items:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <guimenuitem>Properties...</guimenuitem> &mdash; This menu
+ item opens the <interface>Properties</interface> dialog (see
+ <xref linkend="GNOMEAPPLET-properties">) which allows you to
+ customize the appearance and behavior of this applet.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <guimenuitem>Run Hello World...</guimenuitem> &mdash; This
+ menu item starts the program <application>Hello
+ World</application>, used to say "hello" to the world.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect2>
+
+ <sect2 id="GNOMEAPPLET-properties">
+ <title>Properties</title>
+ <para>
+ You can configure <application>GNOMEAPPLET</application> applet by
+ right-clicking on the applet and choosing the
+ <guimenuitem>Properties...</guimenuitem> menu item. This will open the
+ <interface>Properties</interface> dialog, shown in <xref
+ linkend="GNOMEAPPLET-properties-fig">.
+ </para>
+ <figure id="GNOMEAPPLET-properties-fig">
+ <title>Properties Dialog</title>
+ <screenshot>
+ <screeninfo>Properties Dialog</screeninfo>
+ <graphic format="png" fileref="GNOMEAPPLET-properties" srccredit="ME">
+ </graphic>
+ </screenshot>
+ </figure>
+
+ <para>
+ To change the color of the applet, click on the
+ <guibutton>color</guibutton> button. To change other properties,
+ click on other buttons.
+ </para>
+
+ <para>
+ For more information on the <interface>Properties</interface>
+ dialog, including descriptions of the <guibutton>OK</guibutton>,
+ <guibutton>Apply</guibutton>, <guibutton>Cancel</guibutton>, and
+ <guibutton>Help</guibutton> buttons, see <xref
+ linkend="applet-properties-dialog">.
+ </para>
+ </sect2>
+
+ <sect2 id="GNOMEAPPLET-bugs">
+ <title> Known Bugs and Limitations</title>
+ <para>
+ There are no known bugs in the
+ <application>GNOMEAPPLET</application> applet.
+ </para>
+ </sect2>
+
+ <sect2 id="GNOMEAPPLET-authors">
+ <title>Authors</title>
+ <para>
+ This applet was writen by HACKER-NAME
+ <email>HACKER-EMAIL</email>. The documentation for this applet
+ which you are reading now was written by
+ YOUR-NAME <email>YOUR-EMAIL</email>. For information on submitting
+ bug reports and suggestions for improvements, see <xref
+ linkend="feedback">.
+ </para>
+ </sect2>
+
+ </sect1>
+
+
+
+
+
+
+
+
+</pre>
+ </p>
+</div>
+<div class="navfooter">
+<hr>
+<table width="100%" summary="Navigation footer">
+<tr>
+<td width="40%" align="left">
+<a href="apas17.html">Prev</a> </td>
+<td width="20%" align="center"><a href="index.html">Home</a></td>
+<td width="40%" align="right"> </td>
+</tr>
+<tr>
+<td width="40%" align="left">Template 2: Applet Manual For GNOME 1.x </td>
+<td width="20%" align="center"><a href="apa.html">Up</a></td>
+<td width="40%" align="right"> </td>
+</tr>
+</table>
+</div>
+</body>
+</html>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
+<html>
+<head>
+<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
+<title>The GNOME Handbook of Writing Software Documentation</title>
+<meta name="generator" content="DocBook XSL Stylesheets V1.40">
+<link rel="home" href="index.html" title="The GNOME Handbook of Writing Software Documentation">
+<link rel="next" href="indexs02.html" title="Getting Started Writing GNOME Documentation">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<div class="navheader">
+<table width="100%" summary="Navigation header">
+<tr><th colspan="3" align="center">The GNOME Handbook of Writing Software Documentation</th></tr>
+<tr>
+<td width="20%" align="left"> </td>
+<th width="60%" align="center"> </th>
+<td width="20%" align="right"> <a href="indexs02.html">Next</a>
+</td>
+</tr>
+</table>
+<hr>
+</div>
+<div class="article">
+<div class="titlepage">
+<div><h2 class="title">
+<a name="index"></a>The GNOME Handbook of Writing Software Documentation</h2></div>
+<div>
+<h3 class="author">David Mason</h3>
+<div class="affiliation">
+<span class="orgname">Red Hat, Inc.<br></span><div class="address">
+<br>
+ <tt><<a href="mailto:dcm@redhat.com">dcm@redhat.com</a>></tt><br>
+ </div>
+</div>
+<h3 class="author">Daniel Mueth</h3>
+<div class="affiliation"><div class="address">
+<br>
+ <tt><<a href="mailto:d-mueth@uchicago.edu">d-mueth@uchicago.edu</a>></tt><br>
+ </div></div>
+<h3 class="author">Alexander Kirillov</h3>
+<div class="affiliation"><div class="address">
+<br>
+ <tt><<a href="mailto:kirillov@math.sunysb.edu">kirillov@math.sunysb.edu</a>></tt><br>
+ </div></div>
+</div>
+<div><p class="releaseinfo">
+ This is a pre-release!
+ </p></div>
+<div><p class="copyright">Copyright © 2000 Red Hat, Inc., Daniel Mueth, and Alexander Kirillov</p></div>
+<div><div class="legalnotice">
+<p>
+ Permission is granted to copy, distribute and/or modify this
+ document under the terms of the <i>GNU Free Documentation
+ License</i>, Version 1.1 or any later version published
+ by the Free Software Foundation with no Invariant Sections, no
+ Front-Cover Texts, and no Back-Cover Texts. You may obtain a copy
+ of the <i>GNU Free Documentation License</i> from
+ the Free Software Foundation by visiting <a href="http://www.fsf.org" target="_top">their Web site</a> or by writing to:
+ Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+ Boston, MA 02111-1307, USA.
+ </p>
+<p>
+ Many of the names used by companies to distinguish their products and
+ services are claimed as trademarks. Where those names appear in any
+ GNOME documentation, and those trademarks are made aware to the members
+ of the GNOME Documentation Project, the names have been printed in caps
+ or initial caps.
+ </p>
+</div></div>
+<div><div class="revhistory"><table border="1" width="100%" summary="Revision history">
+<tr><th align="left" valign="top" colspan="2"><b>Revision History</b></th></tr>
+<tr>
+<td align="left">Revision
+ 0.99
+ </td>
+<td align="left">
+ 04.10.2000
+ </td>
+</tr>
+</table></div></div>
+<hr>
+</div>
+<div class="toc">
+<p><b>Table of Contents</b></p>
+<dl>
+<dt> <a href="index.html#intro">Introduction</a>
+</dt>
+<dd><dl>
+<dt> <a href="index.html#gdp">The GNOME Documentation Project</a>
+</dt>
+<dt> <a href="index.html#notation">Notation and Conventions</a>
+</dt>
+<dt> <a href="index.html#about">About This Handbook</a>
+</dt>
+</dl></dd>
+<dt> <a href="indexs02.html">Getting Started Writing GNOME Documentation</a>
+</dt>
+<dd><dl>
+<dt> <a href="indexs02.html#selecting">Selecting A Document</a>
+</dt>
+<dt> <a href="indexs02.html#docbook">Installing and Using DocBook</a>
+</dt>
+<dt> <a href="indexs02.html#gdptemplates">GDP Document Templates</a>
+</dt>
+<dt> <a href="indexs02.html#screenshots">Screenshots</a>
+</dt>
+<dt> <a href="indexs02.html#applicationbugs">Application Bugs</a>
+</dt>
+<dt> <a href="indexs02.html#cvs">Using CVS</a>
+</dt>
+</dl></dd>
+<dt> <a href="indexs03.html">The GNOME Documentation System</a>
+</dt>
+<dd><dl>
+<dt> <a href="indexs03.html#gnomehelpbrowser">The GNOME Help Browser</a>
+</dt>
+<dt> <a href="indexs03.html#gnomehelpbrowser2">The GNOME Help Browser (GNOME-2.0)</a>
+</dt>
+<dt> <a href="indexs03.html#gnomehelponthefly">Dynamic Document Synthesis(GNOME-2.0)</a>
+</dt>
+<dt> <a href="indexs03.html#gnomehelpcomponents">The GNOME Documentation Components</a>
+</dt>
+</dl></dd>
+<dt> <a href="indexs04.html">DocBook Basics </a>
+</dt>
+<dd><dl>
+<dt> <a href="indexs04.html#introtodocbook">Introduction to DocBook</a>
+</dt>
+<dt> <a href="indexs04.html#xml">XML and SGML</a>
+</dt>
+<dt> <a href="indexs04.html#structure"> Structure Elements</a>
+</dt>
+<dt> <a href="indexs04.html#inline">Inline Elements</a>
+</dt>
+</dl></dd>
+<dt> <a href="indexs05.html">GDP Documentation Conventions </a>
+</dt>
+<dd><dl>
+<dt> <a href="indexs05.html#conventionsalldocs">Conventions for All GDP Documentation</a>
+</dt>
+<dt> <a href="indexs05.html#conventionsappdocs">Conventions for Application Documentation</a>
+</dt>
+</dl></dd>
+<dt> <a href="indexs06.html">Writing Application and Applet Manuals</a>
+</dt>
+<dt> <a href="indexs07.html">Listing Documents in the Help Menu</a>
+</dt>
+<dt> <a href="indexs08.html">Application Help Buttons</a>
+</dt>
+<dt> <a href="indexs09.html">Packaging Applet Documentation</a>
+</dt>
+<dd><dl>
+<dt> <a href="indexs09.html#appletfiles">Applet Documentation Files</a>
+</dt>
+<dt> <a href="indexs09.html#appletmenu">Adding Documentation to an Applet Menu</a>
+</dt>
+</dl></dd>
+<dt> <a href="indexs10.html">Writing Context Sensitive Help (coming in GNOME-2.0)</a>
+</dt>
+<dt> <a href="indexs11.html">Referring to Other GNOME Documentation (coming in
+ GNOME-2.0)</a>
+</dt>
+<dt> <a href="indexs12.html">Basics of Documentation Style</a>
+</dt>
+<dd><dl>
+<dt> <a href="indexs12.html#styleplanning">Planning</a>
+</dt>
+<dt> <a href="indexs12.html#balance">Achieving a Balanced Style</a>
+</dt>
+<dt> <a href="indexs12.html#stylestructure">Structure</a>
+</dt>
+<dt> <a href="indexs12.html#stylegrammar">Grammar and Spelling</a>
+</dt>
+</dl></dd>
+<dt> <a href="indexs13.html">Teamwork</a>
+</dt>
+<dd><dl>
+<dt> <a href="indexs13.html#teamworkgdp">Working With The GDP Team</a>
+</dt>
+<dt> <a href="indexs13.html#teamworkdevelopers">Working With Developers</a>
+</dt>
+</dl></dd>
+<dt> <a href="indexs14.html">Finishing A Document</a>
+</dt>
+<dd><dl>
+<dt> <a href="indexs14.html#editting">Editing The Document</a>
+</dt>
+<dt> <a href="indexs14.html#submitting">Submitting The Document</a>
+</dt>
+</dl></dd>
+<dt> <a href="indexs15.html">Resources</a>
+</dt>
+<dd><dl>
+<dt> <a href="indexs15.html#resourcesweb">Resources On The Web</a>
+</dt>
+<dt> <a href="indexs15.html#resourcesbooks">Books</a>
+</dt>
+<dt> <a href="indexs15.html#mailinglists">Mailing Lists</a>
+</dt>
+<dt> <a href="indexs15.html#irc">IRC</a>
+</dt>
+</dl></dd>
+<dt>A <a href="apa.html">Document Templates</a>
+</dt>
+<dd><dl>
+<dt> <a href="apa.html#template1">Template 1: Application Manual</a>
+</dt>
+<dt> <a href="apas17.html">Template 2: Applet Manual For GNOME 1.x</a>
+</dt>
+<dt> <a href="apas18.html">Template 2: Applet Manual For GNOME 2.x</a>
+</dt>
+</dl></dd>
+</dl>
+</div>
+<div class="sect1">
+<a name="intro"></a><div class="titlepage"><div><h2 class="title" style="clear: both">
+<a name="intro"></a>Introduction</h2></div></div>
+<div class="sect2">
+<a name="gdp"></a><div class="titlepage"><div><h3 class="title">
+<a name="gdp"></a>The GNOME Documentation Project</h3></div></div>
+<div class="sect3">
+<a name="goals"></a><div class="titlepage"><div><h4 class="title">
+<a name="goals"></a>Goals</h4></div></div>
+<p>
+ The GNOME Documentation Project (GDP) aims to provide GNOME
+ and GNOME applications with a complete, intuitive, and clear
+ documentation system. At the center of the GDP is the
+ GNOME Help Browser, which
+ presents a unified interface to GNOME-specific documentation
+ as well as other Linux documentation such as man pages and
+ texinfo documents. The GNOME Help System provides a
+ comprehensive view of documentation on a machine by
+ dynamically assembling the documentation of GNOME
+ applications and components which are installed. The GDP is
+ responsible for writing numerous GNOME-related documents,
+ both for developers and for users. Developer documentation
+ includes <a href="http://developer.gnome.org/doc/API/" target="_top">APIs for the GNOME libraries</a>, <a href="http://developer.gnome.org/doc/whitepapers/" target="_top"><i>GNOME White
+ Papers</i></a>, GNOME developer <a href="http://developer.gnome.org/doc/tutorials/" target="_top">tutorials</a>, the <a href="http://developer.gnome.org/doc/FAQ/" target="_top"><i>GNOME Developer
+ FAQ</i></a>, the <a href="http://developer.gnome.org" target="_top">GNOME
+ Developer's Website</a>, and <i>GNOME
+ Handbook</i>'s, such as the one you are reading.
+ User documentation include the <a href="http://www.gnome.org/learn/" target="_top"><i>GNOME User's
+ Guide</i></a>, the <a href="http://www.gnome.org/learn/" target="_top"><i>GNOME FAQ</i></a>, and
+ GNOME application documentation. Most GNOME applications
+ have their own manual in addition to context sensitive help.
+ </p>
+</div>
+<div class="sect3">
+<a name="joining"></a><div class="titlepage"><div><h4 class="title">
+<a name="joining"></a>Joining the GDP</h4></div></div>
+<p>
+ Documenting GNOME and all the numerous GNOME applications is
+ a very large project. The GDP is always looking for people
+ to help write, update, and edit documentation. If you are
+ interested in joining the GDP team, you should join the
+ <a href="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/" target="_top">
+ <i>gnome-doc-list mailing list</i> </a>.
+ Read <a href="indexs02.html" title="Getting Started Writing GNOME Documentation">the section called “Getting Started Writing GNOME Documentation”</a>, for help selecting a
+ project to work on. Feel free to introduce yourself on the
+ gnome-doc-list mailing list and indicate which project you
+ intend to work on, or else ask for suggestions of important
+ documents which need work done. You may also want to join the
+ #docs IRC channel on irc.gnome.org to meet other GDP members
+ and discuss any questions you may have. For a list of GDP
+ projects and members, see the
+ <a href="http://developer.gnome.org/projects/gdp" target="_top">
+ <i>GDP Website</i></a>.
+ </p>
+</div>
+<div class="sect3">
+<a name="collaborating"></a><div class="titlepage"><div><h4 class="title">
+<a name="collaborating"></a>Collaborating with the GDP</h4></div></div>
+<p>
+ GNOME developers, packagers, and translators may not be
+ writing GNOME documentation but will want to understand how
+ the GNOME documentation system works and will need to
+ collaborate with GDP members. This document should help to
+ outline the structure of how the GNOME documentation system
+ works. Developers who do not write the documentation for
+ their applications are encouraged to find a GDP member to
+ write the documentation. This is best done by sending an
+ email to the <a href="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/" target="_top">
+ <i>gnome-doc-list mailing list</i> </a>
+ describing the application, where it can be downloaded from,
+ and that the developer(s) would like a GDP member to write
+ documentation for the application. The #docs IRC channel on
+ irc.gnome.org is another option for contacting GDP members.
+ </p>
+</div>
+</div>
+<div class="sect2">
+<a name="notation"></a><div class="titlepage"><div><h3 class="title">
+<a name="notation"></a>Notation and Conventions</h3></div></div>
+<p>
+ This Handbook uses the following notation:
+ <div class="informaltable" id="id2785550">
+<a name="id2785550"></a><table border="0">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<tbody>
+<tr>
+<td><tt>/usr/bin</tt></td>
+<td>
+ Directory
+ </td>
+</tr>
+<tr>
+<td><tt>foo.sgml</tt></td>
+<td>
+ Filename
+ </td>
+</tr>
+<tr>
+<td><b>command</b></td>
+<td>
+ Command or text that would be typed.
+ </td>
+</tr>
+<tr>
+<td><b><i><tt>replaceable</tt></i></b></td>
+<td>
+ "Variable" text that can be replaced.
+ </td>
+</tr>
+<tr>
+<td><tt>Program or Doc Code</tt></td>
+<td>Program or document code</td>
+</tr>
+</tbody>
+</table>
+</div>
+ </p>
+</div>
+<div class="sect2">
+<a name="about"></a><div class="titlepage"><div><h3 class="title">
+<a name="about"></a>About This Handbook</h3></div></div>
+<p>
+ This Handbook is a guide for both writing documentation for
+ GNOME components and applications and for properly binding and
+ packaging documentation into GNOME applications.
+ </p>
+<p>
+ This Handbook, like all GNOME documentation, was written in
+ DocBook(SGML) and is available in several formats including
+ SGML, HTML, PostScript, and PDF. For the latest version, see
+ <a href="http://developer.gnome.org/projects/gdp/handbook.html" target="_top">
+ <i>Getting The GNOME Handbook of Writing Software
+ Documentation</i> </a>. Alternately, one may
+ download it anonymously from GNOME CVS under <tt>gnome-docu/gdp</tt>.
+ </p>
+</div>
+</div>
+</div>
+<div class="navfooter">
+<hr>
+<table width="100%" summary="Navigation footer">
+<tr>
+<td width="40%" align="left"> </td>
+<td width="20%" align="center"> </td>
+<td width="40%" align="right"> <a href="indexs02.html">Next</a>
+</td>
+</tr>
+<tr>
+<td width="40%" align="left"> </td>
+<td width="20%" align="center"> </td>
+<td width="40%" align="right"> Getting Started Writing GNOME Documentation</td>
+</tr>
+</table>
+</div>
+</body>
+</html>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
+<html>
+<head>
+<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
+<title>Getting Started Writing GNOME Documentation</title>
+<meta name="generator" content="DocBook XSL Stylesheets V1.40">
+<link rel="home" href="index.html" title="The GNOME Handbook of Writing Software Documentation">
+<link rel="up" href="index.html" title="The GNOME Handbook of Writing Software Documentation">
+<link rel="previous" href="index.html" title="The GNOME Handbook of Writing Software Documentation">
+<link rel="next" href="indexs03.html" title="The GNOME Documentation System">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<div class="navheader">
+<table width="100%" summary="Navigation header">
+<tr><th colspan="3" align="center">Getting Started Writing GNOME Documentation</th></tr>
+<tr>
+<td width="20%" align="left">
+<a href="index.html">Prev</a> </td>
+<th width="60%" align="center"> </th>
+<td width="20%" align="right"> <a href="indexs03.html">Next</a>
+</td>
+</tr>
+</table>
+<hr>
+</div>
+<div class="sect1">
+<a name="gettingstarted"></a><div class="titlepage"><div><h2 class="title" style="clear: both">
+<a name="gettingstarted"></a>Getting Started Writing GNOME Documentation</h2></div></div>
+<div class="sect2">
+<a name="selecting"></a><div class="titlepage"><div><h3 class="title">
+<a name="selecting"></a>Selecting A Document</h3></div></div>
+<div class="sect3">
+<a name="know"></a><div class="titlepage"><div><h4 class="title">
+<a name="know"></a>Document Something You Know</h4></div></div>
+<p>
+ The most frequently asked question of new contributors who
+ join the GDP is "which document should I start
+ with?". Because most people involved are volunteers, we do
+ not <i>assign</i> projects and applications to
+ write documents for. The first step is all yours - you must
+ decide what about GNOME interests you most and find out if
+ it has complete documents or not.
+ </p>
+<p>
+ It is also important to spend some time with GNOME to make
+ sure you are familiar enough with it to be
+ <i>authoritative</i> in your writing. The
+ best way to do this is to just sit down and play with GNOME
+ as much as possible before starting to write.
+ </p>
+<p>
+ The easiest way to get started is to improve existing
+ documentation. If you notice some inaccuracies or omissions
+ in the documentation, or you think that you can explain the
+ material more clearly, just send your suggestions to the
+ author of the original documentation or to the GNOME
+ documentation project at <tt><<a href="mailto:docs@gnome.org">docs@gnome.org</a>></tt>.
+ </p>
+</div>
+<div class="sect3">
+<a name="doctable"></a><div class="titlepage"><div><h4 class="title">
+<a name="doctable"></a>The GNOME Documentation Status Table</h4></div></div>
+<p>
+ The <i>GDP Documentation Status Table</i>
+ (<i>DocTable</i>) (<a href="http://www.gnome.org/gdp/doctable/" target="_top">http://www.gnome.org/gdp/doctable/</a>) is a
+ web page which tracks the status of all the various
+ documentation components of GNOME. These components include
+ application documentation, internal GNOME component
+ documentation, user documentation, and developer
+ documentation. For each documentation item, it tracks the
+ current status of the documentation, who is working on the
+ particular document, where the documentation can be found,
+ and provides a forum for the discussion of each item.
+ </p>
+<p>
+ You should use the <i>DocTable</i> to help
+ you select a documentation item which needs work done. Once
+ you have selected an item to work on, please register
+ yourself as an author so that other authors do not duplicate
+ your work and may contact you to help or offer suggestions.
+ Also be sure to keep the status icons up-to-date so that
+ the GDP team can easily identify which items need additional
+ help. The <i>DocTable</i> also allows
+ people to make announcements and suggestions and to discuss
+ issues in the comments section.
+ </p>
+<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
+<h3 class="title">
+<a name="id2779702"></a>Note</h3>
+<p>
+ Note that the information in the
+ <i>DocTable</i> may not always be up-to-date
+ or accurate. When you assign yourself to documenting an
+ application, make sure you find out the latest status of
+ documentation by contacting the application author.
+ </p>
+</div>
+</div>
+</div>
+<div class="sect2">
+<a name="docbook"></a><div class="titlepage"><div><h3 class="title">
+<a name="docbook"></a>Installing and Using DocBook</h3></div></div>
+<p>
+ All documentation for the GNOME project is written in SGML
+ using the DocBook DTD. There are many advantages to using
+ this for documentation, not least of which is the single
+ source nature of SGML. To contribute to the GDP you should
+ learn to use DocBook.
+ </p>
+<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
+<h3 class="title">
+<a name="id2779790"></a>NOTE</h3>
+<p>
+ To get started writing for the GDP you do not need to rush
+ out and learn DocBook - if you feel it is too much to handle
+ for now, you can submit plain ASCII text to the <a href="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/" target="_top">
+ <i>gnome-doc-list mailing list</i>
+ </a>and a volunteer will mark it up for you. Seeing your
+ document marked up will also be a great way for you to start
+ learning DocBook.
+ </p>
+</div>
+<div class="sect3">
+<a name="installingdocbook"></a><div class="titlepage"><div><h4 class="title">
+<a name="installingdocbook"></a>Installing DocBook</h4></div></div>
+<p>
+ Download and install the following <a href="ftp://sourceware.cygnus.com:/pub/docbook-tools/" target="_top">DocBook Tools packages</a>: jade, docbook,
+ jadetex, sgml-common, and stylesheets. (RPM users should note
+ that jade is platform dependent (eg. i386), while the other packages
+ are in the <tt>noarch</tt>
+ directory.) You can find more
+ information on DocBook Tools <a href=" http://sourceware.cygnus.com/docbook-tools/" target="_top">here</a>.
+ </p>
+<p>
+ If you are an Emacs user you may
+ want to grab the psgml package as well. This is a major mode
+ for editing sgml files in Emacs.
+ </p>
+</div>
+<div class="sect3">
+<a name="gdpstylesheets"></a><div class="titlepage"><div><h4 class="title">
+<a name="gdpstylesheets"></a>GDP Stylesheets</h4></div></div>
+<p>
+ The GDP uses its own DocBook stylesheets. To use the GDP
+ stylesheets, you should download the file
+ <tt>gdp-both.dsl</tt> from the <tt>gnome-docu/gdp/dsssl</tt> module in
+ CVS (or from <a href="http://developer.gnome.org/projects/gdp/stylesheets.html" target="_top">
+ GDP Custom DSSSL Stylesheet</a>)and copy it
+
+ over the file
+ <tt>/usr/lib/sgml/stylesheets/cygnus-both.dsl</tt>.
+ Alternately, you can download and install the
+ <a href="http://people.redhat.com/dcm/software.html" target="_top">gnome-doc-tools package</a> which will set
+ up the stylesheets as well as the DTD discussed below.
+ </p>
+</div>
+<div class="sect3">
+<a name="gdpdtd"></a><div class="titlepage"><div><h4 class="title">
+<a name="gdpdtd"></a>GDP DTD (PNG Image Support)</h4></div></div>
+<p>
+ Due to some license issues involved with the creation of
+ gifs, the GNOME Documentation Project has decided to use the
+ PNG image format for all images in GNOME documentation. You
+ can read more about the issues involved with gifs at <a href="http://www.gnu.org/philosophy/gif.html" target="_top">http://www.gnu.org/philosophy/gif.html</a>.
+ </p>
+<p>
+ The current DocBook DTD(3.1) does not include support for
+ embedding PNG images in your documents. Since the GDP uses
+ many screenshots in its documentation, we use our own
+ variation on the DocBook DTD which has PNG image support.
+ We encourage everybody to use this DTD instead of the
+ default DocBook DTD since your source document header and
+ your output document appearance subtly vary between the two
+ DTD's. To install the GDP custom DTD with PNG image support
+ by hand:
+ </p>
+<div class="itemizedlist"><ul>
+<li><p>
+<a name="id2780178"></a>
+ Download <a href="http://www.labs.redhat.com/png/png-support.html" target="_top">the
+ GDP DocBook DTD for PNG support</a> and install it
+ where you keep your DTD's. (On Red Hat use <tt>/usr/lib/sgml/</tt>.) Note that
+ the 3.0 DTD is missing support for the
+ <tt><legalnotice></tt> tag, so it is
+ recommended that you use version 3.1
+ </p></li>
+<li style="list-style-type: disc"><p>
+<a name="id2780346"></a>
+ Add the new DTD to your SGML CATALOG file. The location
+ of your SGML CATALOG file may vary depending upon your
+ distribution. (On Red Hat it is usually in
+ /usr/lib/sgml/CATALOG.) Add the following line to this
+ file:
+ <pre class="programlisting">
+PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.0//EN" "png-support-3.0.dtd"
+ </pre>
+ If you are using the 3.1 DTD, use:
+ <pre class="programlisting">
+PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN" "png-support-3.1.dtd"
+ </pre>
+ </p></li>
+</ul></div>
+<p>
+ Alternately, you can download and install the
+ <a href="http://people.redhat.com/dcm/software.html" target="_top">gnome-doc-tools package</a> which will set
+ up the custom stylesheets and DTD for you.
+ </p>
+<p>
+ To include PNG files in your documents, you will need to
+ indicate that you are using this special DTD. To do
+ this, use the following headers:
+ </p>
+<p>
+ Articles:
+ <pre class="programlisting">
+<!DOCTYPE Article PUBLIC "-//GNOME//DTD DocBook PNG Variant
+V1.1//EN"[]>
+ </pre>
+ </p>
+<p>
+ Books:
+ <pre class="programlisting">
+<!DOCTYPE Book PUBLIC "-//GNOME//DTD DocBook PNG Variant
+V1.1//EN"[]>
+ </pre>
+ </p>
+</div>
+<div class="sect3">
+<a name="editors"></a><div class="titlepage"><div><h4 class="title">
+<a name="editors"></a>Editors</h4></div></div>
+<p>
+ There are many editors on Linux and UNIX systems available
+ to you. Which editor you use to work on the sgml documents
+ is completely up to you, as long as the editor is able to
+ preserve sgml and produce the source in a format that is
+ readable by everyone.
+ </p>
+<p>
+ Probably the two most popular editors available are
+ Emacs and
+ vi. These and other editors are
+ used regularly by members of the GDP. Emacs has a major
+ mode, psgml, for editing sgml files which can save you time
+ and effort in adding and closing tags. You will find the
+ psgml package in DocBook Tools, which is the standard set of
+ tools for the GDP. You may find out more about DocBook Tools
+ in <a href="indexs02.html#installingdocbook" title="Installing DocBook">the section called “Installing DocBook”</a>.
+ </p>
+</div>
+<div class="sect3">
+<a name="make-output"></a><div class="titlepage"><div><h4 class="title">
+<a name="make-output"></a>Creating Something Useful with your Docs</h4></div></div>
+<p>
+ The tools available in DocBook Tools allow you to convert
+ your sgml document to many different formats including html
+ and Postscript. The primary tool used to do the conversion
+ is an application called Jade. In
+ most cases you will not have to work directly with
+ Jade; Instead, you will use the
+ scripts provided by DocBook Tools.
+ </p>
+<p>
+ To preview your DocBook document, it is easiest to convert
+ it to <tt>html</tt>. If you have installed the
+ DocBook tools described above, all you have to do is to run
+ the command <tt>$</tt><b>db2html
+ mydocument.sgml</b>. If there are no sgml syntax
+ errors, this will create a directory <tt>mydocument</tt> and place the
+ resulting html files in it. The title page of the document
+ will typically be
+ <tt>mydocument/index.html</tt>. If you have
+ screenshots in your document, you will have to copy these
+ files into the <tt>mydocument</tt> directory by
+ hand. You can use any web browser to view your document.
+ Note that every time you run <b>db2html</b>, it
+ creates the <tt>mydocument</tt> directory over, so
+ you will have to copy the screenshots over each time.
+ </p>
+<p>
+ You can also convert your document to PostScript by running
+ the command <tt>$</tt><b>db2ps
+ mydocument.sgml</b>, after which you can print out or
+ view the resulting .ps file.
+ </p>
+<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
+<h3 class="title">
+<a name="id2780250"></a>NOTE</h3>
+<p>
+ The html files you get will not look quite the same as the
+ documentation distributed with GNOME unless you have the
+ custom stylesheets installed on your machine. DocBook
+ Tools' default stylesheets will produce a different look
+ to your docs. You can read more about the GDP stylesheets
+ in <a href="indexs02.html#gdpstylesheets" title="GDP Stylesheets">the section called “GDP Stylesheets”</a>.
+ </p>
+</div>
+</div>
+<div class="sect3">
+<a name="jadeimages"></a><div class="titlepage"><div><h4 class="title">
+<a name="jadeimages"></a>Images in DocBook Tools</h4></div></div>
+<p>
+ If your document uses images you will need to take note of a
+ few things that should take place in order for you to make
+ use of those images in your output.
+ </p>
+<p>
+ The DocBook Tools scripts and applications are smart enough
+ to know that when you are creating html you will be using
+ PNG files and when you are creating Postscript you will be
+ using EPS files (you must use EPS with Postscript).
+ </p>
+<p>
+ Thus, you should never explicitly
+ include the extension of the image file, since DocBook
+ Tools will automatically insert it for you. For example:
+ </p>
+<pre class="programlisting">
+
+<figure>
+ <title>My Image</title>
+ <screenshot>
+ <screeninfo>Sample GNOME Display</screeninfo>
+ <graphic format="png" fileref="myfile" srccredit="me">
+ </graphic>
+ </screenshot>
+</figure>
+ </pre>
+<p>
+ You will notice in this example that the file
+ <tt>myfile.png</tt> was referred to as simply
+ <tt>myfile</tt>. Now when you run
+ <b>db2html</b> to create an html file, it will
+ automatically look for <tt>myfile.png</tt> in
+ the directory.
+ </p>
+<p>
+ If you want to create PostScript ouput, you will need to create an
+ EPS version of your image file to be displayed in the
+ PostScript file. There is a simple script available which
+ allows you to change a PNG image into an EPS file
+ easily. You can download this file - img2eps - from <a href="http://people.redhat.com/dcm/sgml.html" target="_top">http://people.redhat.com/dcm/sgml.html</a>
+ (look for the img2eps section). Note that this script is
+ included in the gnome-doc-tools package, so if you are using
+ this package, you should already have
+ <b>img2eps</b> on you system.
+ </p>
+</div>
+<div class="sect3">
+<a name="moredocbookinfo"></a><div class="titlepage"><div><h4 class="title">
+<a name="moredocbookinfo"></a>Learning DocBook</h4></div></div>
+<p>
+ There are many resources available to help you learn DocBook.
+ The following resources on the web are useful for learning
+ DocBook:
+ </p>
+<div class="itemizedlist"><ul>
+<li><p>
+<a name="id2902492"></a>
+ <a href="http://www.docbook.org" target="_top">http://www.docbook.org</a> - Norman
+ Walsh's <i>DocBook: The Definitive
+ Guide</i>. Online O'Reilly book on using
+ DocBook. Contains an excellent element reference. May be
+ too formal for a beginner.
+ </p></li>
+<li><p>
+<a name="id2902547"></a>
+ <a href="http://www.oswg.org/oswg-nightly/oswg/en_US.ISO_8859-1/articles/DocBook-Intro/docbook-intro/index.html" target="_top">A Practical Introduction to DocBook</a>
+ - The Open Source Writers Group's introduction to using
+ DocBook. This is an excellent HOW-TO type article on
+ getting started.
+ </p></li>
+<li><p>
+<a name="id2902588"></a>
+ <a href="http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro/docbook-intro.html" target="_top">Getting Going with DocBook: Notes for
+ Hackers</a> - Mark Galassi's introduction to DocBook
+ for hackers. This has to be one of the first
+ introductions to DocBook ever - still as good as it ever
+ was.
+ </p></li>
+<li><p>
+<a name="id2902627"></a>
+ <a href="http://www.freebsd.org/tutorials/docproj-primer/" target="_top">
+ FreeBSD Documentation Project Primer for New
+ Contributors</a> - FreeBSD documentation project
+ primer. Chapter 4.2 provides a very good introduction to
+ writing documentation using DocBook. Note that it also
+ describes some custom extensions of DocBook;
+ fortunately, they are clearly marked as such.
+ </p></li>
+</ul></div>
+<p>
+ Norman Walsh's book is also available in print.
+ </p>
+<p>
+ The following sections of this document are designed to help
+ documentation authors write correct and consistent DocBook:
+ </p>
+<div class="itemizedlist"><ul><li><p>
+<a name="id2902694"></a>
+ <a href="indexs04.html" title="DocBook Basics ">the section called “DocBook Basics ”</a> - Descriptions of
+ commonly used DocBook tags.
+ </p></li></ul></div>
+<p>
+ You may also discuss specific DocBook questions with GDP
+ members on the #docs IRC channel at irc.gnome.org and on the
+ gnome-doc-list mailing list.
+ </p>
+</div>
+</div>
+<div class="sect2">
+<a name="gdptemplates"></a><div class="titlepage"><div><h3 class="title">
+<a name="gdptemplates"></a>GDP Document Templates</h3></div></div>
+<p>
+ Templates for various types of GNOME documents are found in
+ <a href="apa.html" title="A. Document Templates">Appendix A. Document Templates</a>. They are kept in CVS in
+ gnome-docu/gdp/templates. The easiest source to get them from
+ is probably the <a href="http://developer.gnome.org/projects/gdp/templates.html" target="_top">GDP
+ Document Templates</a> web page, which is typically kept
+ completely up-to-date with CVS and has a basic description of
+ each file from CVS.
+ </p>
+</div>
+<div class="sect2">
+<a name="screenshots"></a><div class="titlepage"><div><h3 class="title">
+<a name="screenshots"></a>Screenshots</h3></div></div>
+<p>
+ Most GNOME documents will have screenshots of the particular
+ applet, application, GNOME component, or widget being
+ discussed. As discussed above in <a href="indexs02.html#gdpdtd" title="GDP DTD (PNG Image Support)">the section called “GDP DTD (PNG Image Support)”</a> you
+ will need to install the special GDP DocBook DTD which
+ supports PNG images, the format used for all images in GNOME
+ documentation. For the basic DocBook structure used to insert
+ images in a document, see <a href="indexs02.html#jadeimages" title="Images in DocBook Tools">the section called “Images in DocBook Tools”</a> above.
+ </p>
+<div class="sect3">
+<a name="screenshotappearance"></a><div class="titlepage"><div><h4 class="title">
+<a name="screenshotappearance"></a>Screenshot Appearance</h4></div></div>
+<p>
+ For all screenshots of windows that typically have border
+ decorations (e.g. applications and dialogs, but not applets
+ in a panel), GDP standards dictate
+ the appearance of the window. (This is to minimize possible
+ confusion to the reader, improve the appearance of GNOME
+ documents, and guarantee the screenshot is readable when
+ printed.) All screenshots should be taken with the SawFish
+ (formerly known as Sawmill) window manager using the
+ MicroGui theme and Helvetica 12pt font. (A different window
+ manager can be used provided the MicroGui theme is available
+ for this window manager and the appearance is identical to
+ that when using the SawFish window manager.) The default
+ GTK+ theme(gtk) and font (Helvetica 12 pt) should be used
+ for all screenshots. If you are unable to provide
+ screenshots in this form, you should create screenshots as
+ you wish them to appear and send them to the
+ <a href="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/" target="_top">
+ <i>gnome-doc-list mailing list</i> </a>
+ requesting a GDP member reproduce these screenshots in the
+ correct format and email them to you.
+ </p>
+</div>
+<div class="sect3">
+<a name="screenshottools"></a><div class="titlepage"><div><h4 class="title">
+<a name="screenshottools"></a>Screenshot Tools</h4></div></div>
+<p>
+ There are many tools for taking screenshots in
+ GNOME/Linux. Perhaps the most convenient is the
+ Screen-Shooter Applet. Just click
+ on the window icon in the applet and then on the window you
+ would like to take a screenshot of. (Note that
+ at the time of this writing, PNG images taken by
+ screenshooter do not appear properly in
+ Netscape or the
+ GNOME Help Browser. You
+ should save your screenshot as a GIF and
+ then use <b>convert filename.gif
+ filename.png</b>.) For applets
+ in a Panel,
+ xv can be used to crop the
+ screenshot to only include the relevant portion of the
+ Panel. Note that
+ xv and
+ gimp can both be used for taking
+ screenshots, cropping screenshots, and converting image
+ formats.
+ </p>
+</div>
+<div class="sect3">
+<a name="screenshotfiles"></a><div class="titlepage"><div><h4 class="title">
+<a name="screenshotfiles"></a>Screenshot Files</h4></div></div>
+<p>
+ Screenshots should be kept in the main documentation
+ directory with your SGML file for applets, or should be
+ kept in a directory called "figs" for application and other
+ documentation. After you use <b>db2html</b> to
+ convert your SGML file to HTML (see <a href="indexs02.html#make-output" title="Creating Something Useful with your Docs">the section called “Creating Something Useful with your Docs”</a>), you will need to copy your
+ screenshots (either the individual PNG files for applet
+ documentation, or the whole "figs" directory for other
+ documentation) into the newly created HTML directory. Note
+ that every time you use <b>db2html</b> the HTML
+ directory is erased and rewritten, so do not store your only
+ copy of the screenshots in that directory. If you wish to
+ create PostScript or PDF output, you will need to manually
+ convert the PNG images to EPS as described in <a href="indexs02.html#jadeimages" title="Images in DocBook Tools">the section called “Images in DocBook Tools”</a>, but will not need to copy these
+ images from their default location, as they are included
+ directly into the output(PostScript of PDF) file.
+ </p>
+</div>
+</div>
+<div class="sect2">
+<a name="applicationbugs"></a><div class="titlepage"><div><h3 class="title">
+<a name="applicationbugs"></a>Application Bugs</h3></div></div>
+<p>
+ Documentation authors tend to investigate and test applets and
+ applications more thoroughly than most
+ users. Often documentation authors will discover one or
+ more bugs in the software. These bugs vary from small ones,
+ such as mis-spelled words or missing
+ About dialogs in the menu, to large
+ ones which cause the applet to crash. As all users, you
+ should be sure to report these bugs so that application
+ developers know of them and can fix them. The easiest way to
+ submit a bug report is by using the Bug
+ Buddy applet which is part of the gnome-applets
+ package.
+ </p>
+</div>
+<div class="sect2">
+<a name="cvs"></a><div class="titlepage"><div><h3 class="title">
+<a name="cvs"></a>Using CVS</h3></div></div>
+<p>
+ CVS (Concurrent Versions System) is a tool that allows
+ multiple developers to concurrently work on a set of
+ documents, keeping track of the modifications made by each
+ person. The files are stored on a server and each developer
+ checks files out, modifies them, and then checks in their
+ modified version of the files. Many GNOME programs and
+ documents are stored in CVS. The GNOME CVS server allows
+ users to anonymously check out CVS files. Most GDP members
+ will need to use anonymous CVS to download the most up-to-date
+ version of documentation or programs. Modified documents will
+ typically be emailed to the the application developer. Core
+ GDP members may also be granted login CVS privileges so they
+ may commit modified files directly to CVS.
+ </p>
+<div class="sect3">
+<a name="anonymouscvs"></a><div class="titlepage"><div><h4 class="title">
+<a name="anonymouscvs"></a>Anonymous CVS</h4></div></div>
+<p>
+ To anonymously check out documents from CVS, you must first
+ log in. From the bash shell, you should set your CVSROOT
+ shell variable with <b> export
+ CVSROOT=':pserver:anonymous@anoncvs.gnome.org:/cvs/gnome'</b>
+ and then login with <b>cvs login</b>(there is no
+ password, just hit return). As an example, we will use the
+ "gnome-docu/gdp" module which contains this and several
+ other documents. To check these documents out for the first
+ time, type <b>cvs -z3 checkout
+ gnome-docu/gdp</b>. After you have this document
+ checked out and you would like to download any updates on
+ the CVS server, use <b>cvs -z3 update -Pd</b>.
+ </p>
+</div>
+<div class="sect3">
+<a name="logincvs"></a><div class="titlepage"><div><h4 class="title">
+<a name="logincvs"></a>Login CVS</h4></div></div>
+<p> If you have been given a
+ login for the GNOME CVS server, you may commit your file
+ modifications to CVS. Be sure to read the following section
+ on CVS etiquette before making any commits to CVS. To log in
+ to the CVS server as user
+ <b><i><tt>username</tt></i></b> with a
+ password, you must first set your CVSROOT shell variable with
+ <b> export
+ CVSROOT=':pserver:<i><tt>username</tt></i>@cvs.gnome.org:/cvs/gnome'</b>.
+ Log in with <b>cvs login</b> and enter your
+ password. You may check out and update modules as described
+ above for anonymous CVS access. As a login CVS user, you may
+ also check modified versions of a file into the CVS server.
+ To check
+ <b><i><tt>filename</tt></i></b> into
+ the CVS server, type <b>cvs -z3 commit
+ <i><tt>filename</tt></i></b>. You will be
+ given a vi editor window to type in a brief log entry,
+ summarizing your changes. The default editor can be changed
+ using the <tt>EDITOR</tt> environment variable or
+ with the <b><tt>-e</tt></b> option. You
+ may also check in any modifications to files in the working
+ directory and subdirectories using <b>cvs -z3
+ commit</b>. To
+ add a new file to the CVS server, use <b>cvs -z3 add
+ <i><tt>filename</tt></i></b>, followed by the
+ commit command.
+ </p>
+</div>
+<div class="sect3">
+<a name="cvsetiquette"></a><div class="titlepage"><div><h4 class="title">
+<a name="cvsetiquette"></a>CVS Etiquette</h4></div></div>
+<p>
+ Because files in CVS are typically used and modified by
+ multiple developers and documentation authors, users should
+ exercise a few simple practices out of courtesy towards the
+ other CVS users and the project leader. First, you should
+ not make CVS commits to a package without first discussing
+ your plans with the project leader. This way, the project
+ leader knows who is modifying the files and generally, what
+ sort of changes/development is being done. Also, whenever a
+ CVS user commits a file to CVS, they should make an entry in
+ the CVS log and in the <tt>ChangeLog</tt> so
+ that other users know who is making modifications and what
+ is being modified. When modifying files created by others,
+ you should follow the indentation scheme used by the initial
+ author.
+ </p>
+</div>
+</div>
+</div>
+<div class="navfooter">
+<hr>
+<table width="100%" summary="Navigation footer">
+<tr>
+<td width="40%" align="left">
+<a href="index.html">Prev</a> </td>
+<td width="20%" align="center"><a href="index.html">Home</a></td>
+<td width="40%" align="right"> <a href="indexs03.html">Next</a>
+</td>
+</tr>
+<tr>
+<td width="40%" align="left">The GNOME Handbook of Writing Software Documentation </td>
+<td width="20%" align="center"><a href="index.html">Up</a></td>
+<td width="40%" align="right"> The GNOME Documentation System</td>
+</tr>
+</table>
+</div>
+</body>
+</html>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
+<html>
+<head>
+<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
+<title>The GNOME Documentation System</title>
+<meta name="generator" content="DocBook XSL Stylesheets V1.40">
+<link rel="home" href="index.html" title="The GNOME Handbook of Writing Software Documentation">
+<link rel="up" href="index.html" title="The GNOME Handbook of Writing Software Documentation">
+<link rel="previous" href="indexs02.html" title="Getting Started Writing GNOME Documentation">
+<link rel="next" href="indexs04.html" title="DocBook Basics ">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<div class="navheader">
+<table width="100%" summary="Navigation header">
+<tr><th colspan="3" align="center">The GNOME Documentation System</th></tr>
+<tr>
+<td width="20%" align="left">
+<a href="indexs02.html">Prev</a> </td>
+<th width="60%" align="center"> </th>
+<td width="20%" align="right"> <a href="indexs04.html">Next</a>
+</td>
+</tr>
+</table>
+<hr>
+</div>
+<div class="sect1">
+<a name="gnomedocsystem"></a><div class="titlepage"><div><h2 class="title" style="clear: both">
+<a name="gnomedocsystem"></a>The GNOME Documentation System</h2></div></div>
+<div class="sect2">
+<a name="gnomehelpbrowser"></a><div class="titlepage"><div><h3 class="title">
+<a name="gnomehelpbrowser"></a>The GNOME Help Browser</h3></div></div>
+<p>
+ At the core of the GNOME help system is the GNOME
+ Help Browser. The Help
+ Browser provides a unified interface to several
+ distinct documentation systems on Linux/Unix systems: man
+ pages, texinfo pages, Linux Documentation Project(LDP)
+ documents, GNOME application documentation, and other GNOME
+ documents.
+ </p>
+<p>
+ The GNOME Help Browser works by
+ searching standard directories for documents which are to be
+ presented. Thus, the documentation that appears in the GHB is
+ specific to each computer and will typically only represent
+ software that is installed on the computer.
+ </p>
+</div>
+<div class="sect2">
+<a name="gnomehelpbrowser2"></a><div class="titlepage"><div><h3 class="title">
+<a name="gnomehelpbrowser2"></a>The GNOME Help Browser (GNOME-2.0)</h3></div></div>
+<p> In
+ GNOME 2.0, the GNOME Help Browser
+ will be replaced by Nautilus.
+ Nautilus will be the file manager/graphical shell for GNOME 2.0
+ and will also implement a more sophisticated help system than
+ that used by the GNOME Help Browser
+ used in GNOME 1.0. It will read and display DocBook files
+ directly, avoiding the need for duplicating documents in both
+ DocBook and HTML formats. Its display engine for DocBook will
+ be much faster than running jade to
+ convert to HTML for rendering. Because it uses the original
+ DocBook source for documentation, it will be possible to do more
+ sophisticated searching using the meta information included in
+ the documents. And since Nautilus is a virtual file system
+ layer which is Internet-capable, it will be able to find and
+ display documents which are on the web as well as those on the
+ local file system. For more information on
+ Nautilus, visit the #nautilus IRC
+ channel on irc.gnome.org. </p>
+</div>
+<div class="sect2">
+<a name="gnomehelponthefly"></a><div class="titlepage"><div><h3 class="title">
+<a name="gnomehelponthefly"></a>Dynamic Document Synthesis(GNOME-2.0)</h3></div></div>
+<p>
+ GNOME uses the documentation presented by all the various
+ GNOME components and applications installed on the system to
+ present a complete and customized documentation environment
+ describing only components which are currently installed on a
+ users system. Some of this documentation, such as the manuals
+ for applets, will be combined in such a way that it appears to
+ be a single document.
+ </p>
+<p>
+ By using such a system, you can be sure that any GNOME app you
+ install that has documentation will show up in the index,
+ table of contents, any search you do in the help browser.
+ </p>
+</div>
+<div class="sect2">
+<a name="gnomehelpcomponents"></a><div class="titlepage"><div><h3 class="title">
+<a name="gnomehelpcomponents"></a>The GNOME Documentation Components</h3></div></div>
+<div class="sect3">
+<a name="applicationmanualsintro"></a><div class="titlepage"><div><h4 class="title">
+<a name="applicationmanualsintro"></a>Application Manuals</h4></div></div>
+<p>
+ Every GNOME application should have an application manual.
+ An application manual is a document specific to the
+ particular application which explains the various windows
+ and features of the application. Application Manuals
+ typically use screenshots (PNG format) for clarity. Writing
+ application manuals is discussed in more detail in <a href="indexs06.html" title="Writing Application and Applet Manuals">the section called “Writing Application and Applet Manuals”</a> below.
+ </p>
+</div>
+<div class="sect3">
+<a name="applicationhelpintro"></a><div class="titlepage"><div><h4 class="title">
+<a name="applicationhelpintro"></a>Application Help</h4></div></div>
+<p>
+ Applications should have a Help
+ button on screens on which users may need help. These
+ Help buttons should pull up the
+ default help browser, determined by the
+ <tt>ghelp</tt> URL Handler (configured using the
+ Control Center), typically the
+ GNOME Help Browser. The help
+ browser should show either the first page of the application
+ manual, or else the relevant page thereof. Application help
+ is described in more detail in <a href="indexs08.html" title="Application Help Buttons">the section called “Application Help Buttons”</a> below.
+ </p>
+</div>
+<div class="sect3">
+<a name="contextsensitivehelpintro"></a><div class="titlepage"><div><h4 class="title">
+<a name="contextsensitivehelpintro"></a>Application Context Sensitive Help (coming in
+ GNOME-2.0)</h4></div></div>
+<p>
+ Context sensitive help is a system which will allow the user
+ to query any part (button, widget, etc.) of an application
+ window. This is done by either entering a CS Help mode by
+ clicking on an icon or by right clicking on the application
+ part and selecting "What's This" or whatever is decided on
+ at the time. Context sensitive help is described in more
+ detail in <a href="indexs10.html" title="Writing Context Sensitive Help (coming in GNOME-2.0)">the section called “Writing Context Sensitive Help (coming in GNOME-2.0)”</a>
+ below.
+ </p>
+</div>
+<div class="sect3">
+<a name="userguide"></a><div class="titlepage"><div><h4 class="title">
+<a name="userguide"></a>The GNOME User Guide</h4></div></div>
+<p>
+ The <i>GNOME User Guide</i> describes the
+ GNOME desktop environment and core components of GNOME such
+ as the panel and
+ control center. In GNOME 1.x this
+ was the main and only source of documentation. In GNOME 2.0
+ this will become a document for the web and for printing
+ that is derived from various parts chosen in the system that
+ are necessary for the new user to understand.
+ </p>
+</div>
+<div class="sect3">
+<a name="userdocs"></a><div class="titlepage"><div><h4 class="title">
+<a name="userdocs"></a>User Documents</h4></div></div>
+<p>
+ Aside from the <i>GNOME User Guide</i>,
+ there are several other documents to help GNOME users learn
+ GNOME, including the <i>GNOME FAQ</i>,
+ <i>GNOME Installation and Configuration
+ Guide</i>, and the <i>GNOME Administrators
+ Guide</i>.
+ </p>
+</div>
+<div class="sect3">
+<a name="developerdocs"></a><div class="titlepage"><div><h4 class="title">
+<a name="developerdocs"></a>Developer Documents</h4></div></div>
+<p>
+ There are many White Papers, Tutorials, HOWTO's and FAQ's to
+ make programming GNOME and GNOME applications as easy as
+ possible.
+ </p>
+<p>
+ API documentation is also available for the GNOME libraries. This is
+ detailed documentation of the code that is used to build GNOME
+ apps. You can keep up with the GNOME API docs on the <a href="http://developer.gnome.org/doc/API/" target="_top">GNOME API
+ Reference</a> page.
+ </p>
+</div>
+<div class="sect3">
+<a name="projectdocs"></a><div class="titlepage"><div><h4 class="title">
+<a name="projectdocs"></a>Project Documents</h4></div></div>
+<p>
+ Some GNOME projects have documentation to maintain
+ consistency in their product and to help new contributors
+ get up to speed quickly. Among these are the GDP documents,
+ such as the one you are reading now.
+ </p>
+</div>
+</div>
+</div>
+<div class="navfooter">
+<hr>
+<table width="100%" summary="Navigation footer">
+<tr>
+<td width="40%" align="left">
+<a href="indexs02.html">Prev</a> </td>
+<td width="20%" align="center"><a href="index.html">Home</a></td>
+<td width="40%" align="right"> <a href="indexs04.html">Next</a>
+</td>
+</tr>
+<tr>
+<td width="40%" align="left">Getting Started Writing GNOME Documentation </td>
+<td width="20%" align="center"><a href="index.html">Up</a></td>
+<td width="40%" align="right"> DocBook Basics </td>
+</tr>
+</table>
+</div>
+</body>
+</html>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
+<html>
+<head>
+<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
+<title>DocBook Basics </title>
+<meta name="generator" content="DocBook XSL Stylesheets V1.40">
+<link rel="home" href="index.html" title="The GNOME Handbook of Writing Software Documentation">
+<link rel="up" href="index.html" title="The GNOME Handbook of Writing Software Documentation">
+<link rel="previous" href="indexs03.html" title="The GNOME Documentation System">
+<link rel="next" href="indexs05.html" title="GDP Documentation Conventions ">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<div class="navheader">
+<table width="100%" summary="Navigation header">
+<tr><th colspan="3" align="center">DocBook Basics </th></tr>
+<tr>
+<td width="20%" align="left">
+<a href="indexs03.html">Prev</a> </td>
+<th width="60%" align="center"> </th>
+<td width="20%" align="right"> <a href="indexs05.html">Next</a>
+</td>
+</tr>
+</table>
+<hr>
+</div>
+<div class="sect1">
+<a name="docbookbasics"></a><div class="titlepage"><div><h2 class="title" style="clear: both">
+<a name="docbookbasics"></a>DocBook Basics </h2></div></div>
+<div class="sect2">
+<a name="introtodocbook"></a><div class="titlepage"><div><h3 class="title">
+<a name="introtodocbook"></a>Introduction to DocBook</h3></div></div>
+<p>
+ To understand DocBook, a basic understanding of SGML is
+ helpful. SGML stands for Standard General Markup Language and
+ is one of the first markup languages every created. HTML is
+ actually derived from SGML and XML is a subset of SGML. SGML
+ uses what is called a Document Type Definition to specify
+ <i>elements</i> which are contained between
+ brackets, < and >. Text is marked by both beginning and
+ ending elements, for example in the DocBook DTD, one denotes a
+ title with <tt><title></tt>The
+ Title<tt></title></tt>.
+ </p>
+<p>
+ The DTD (in the case of the GDP, DocBook) defines rules for how the
+ elements can be used. For example, if one element can only be used when
+ embedded within another, this is defined in the DTD.
+ </p>
+<p>
+ An SGML file is just a plain ASCII file containing the text
+ with the markup specified above. To convert it to some easily
+ readable format, you need special tools. The GDP uses <i>DocBook
+ Tools</i>, a free package of utilities for working with DocBook
+ which includes <i>Jade</i>, which does the SGML/DSSL
+ parsing. You can read more about DocBook Tools in <a href="indexs02.html#installingdocbook" title="Installing DocBook">the section called “Installing DocBook”</a>.
+ </p>
+<p>
+ The final appearance of the output (e.g. PostScript or HTML)
+ is determined by a
+ <i>stylesheet</i>. Stylesheets are files,
+ written in a special language (DSSSL -- Document Style
+ Semantics and Specification Language), which specify the
+ appearance of various DocBook elements, for example,
+ what fonts to use for titles and various inline elements, page
+ numbering style, and much more. DocBook tools come with a
+ collection of stylesheets (Norman Walsh's modular
+ stylesheets); GNOME Document Project uses some customized
+ version of this stylesheets -- see <a href="indexs02.html#gdpstylesheets" title="GDP Stylesheets">the section called “GDP Stylesheets”</a>.
+ </p>
+<p>
+ The advantage of specifying the <i>structure</i>
+ of a document with SGML instead of specifying the
+ <i>appearance</i> of the document with a typical
+ word processor, or with html, is that the resulting document
+ can be processed in a variety of ways using the structural
+ information. Whereas formatting a document for appearance
+ assumes a medium (typically written text on a standard-sized
+ piece of paper), SGML can be processed to produce output for a
+ large variety of media such as text, postscript, HTML,
+ Braille, audio, and potentially many other formats.
+ </p>
+<p>
+ Using 'content' as the elements to define the text of a document also
+ allows for search engines to make use of the actual elements to make a
+ "smarter search". For example, if you are searching for all documents
+ written by the author "Susie" your search engine could be made smart
+ enough to only search <author> elements, making for a faster and more
+ accurate search.
+ </p>
+<p>
+ Since the overall appearance of the output is determined not by the DTD
+ or the SGML document, but rather by a stylesheet, the appearance of a
+ document can be easily changed just by changing the stylesheet. This
+ allows everyone in the project to create documents that all look the
+ same.
+ </p>
+<p>
+ As stated before, the GDP uses the DocBook DTD. For a list of
+ introductory and reference resources on DocBook, see <a href="indexs15.html" title="Resources">the section called “Resources”</a>. The following sections also provide
+ convenient instructions on which markup tags to use in various
+ circumstances. Be sure to read <a href="indexs05.html" title="GDP Documentation Conventions ">the section called “GDP Documentation Conventions ”</a>
+ for GDP documentation-specific guidelines.
+ </p>
+</div>
+<div class="sect2">
+<a name="xml"></a><div class="titlepage"><div><h3 class="title">
+<a name="xml"></a>XML and SGML</h3></div></div>
+<p> In not so distant future (probably before GNOME 2.0),
+ DocBook itself and GNOME Documentation project will migrate from
+ SGML to XML. This transition should be relatively painless:
+ (almost) all DocBook tags will remain the same. However, XML has
+ stricter syntax rules than SGML; thus, some constructions which
+ are valid in SGML will not be valid in XML. Therefore, to be
+ ready for this transistion, it is <i>strongly
+ advised</i> that the documentation writers conform to XML
+ syntax rules. Here are most important differences:
+ </p>
+<div class="variablelist"><dl>
+<dt>
+<a name="id2904986"></a><span class="term"> <i>Minimization</i></span>
+</dt>
+<dd><p>
+<a name="id2905004"></a>
+ It is possible with some implementations of SGML to use
+ minimizations to close elements in a document by using
+ </>, for example:
+ <tt><tt><title></tt>The
+ Title<tt></></tt></tt>. This is not
+ allowed in XML. You can use <b>sgmlnorm</b> command,
+ included in DocBook Tools package, to expand minimized tags;
+ if you are using Emacs with psgml
+ mode, you can also use menu command
+ Modify->Normalize.
+ </p></dd>
+<dt>
+<a name="id2905087"></a><span class="term"> <i>Self-closing tags</i></span>
+</dt>
+<dd><p>
+<a name="id2905107"></a>
+ Also, in SGML some tags are allowed not to have closing
+ tags. For example, it is legal for
+ <tt><xref></tt> not to have a closing tag:
+ <tt><tt><xref
+ linkend="someid"></tt></tt>. In
+ XML, it is illegal; instead, you should use
+ <tt><tt><xref
+ linkend="someid"/></tt></tt> (note the
+ slash!).
+ </p></dd>
+<dt>
+<a name="id2905160"></a><span class="term"> <i>Case sensitive tags</i></span>
+</dt>
+<dd><p>
+<a name="id2905180"></a>
+ In XML, unlike SGML, tags are case-senstive
+ <tt><title></tt> and
+ <tt><TITLE></tt> are different tags!
+ Therefore, please always use lowercase tags (except for
+ things like <tt>DOCTYPE, CDATA</tt> and
+ <tt>ENTITY</tt>, which are not DocBook tags).
+ </p></dd>
+</dl></div>
+</div>
+<div class="sect2">
+<a name="structure"></a><div class="titlepage"><div><h3 class="title">
+<a name="structure"></a> Structure Elements</h3></div></div>
+<div class="sect3">
+<a name="section"></a><div class="titlepage"><div><h4 class="title">
+<a name="section"></a>Sections and paragraphs</h4></div></div>
+<p>
+ Top-level element of a book body must be
+ <tt><chapter></tt>; it may contain one or more
+ <tt><sect1></tt>, each of them may contain
+ <tt><sect2></tt> and so on up to
+ <tt><sect5></tt>. The top-level element of an
+ article body is always
+ <tt><sect1></tt>. Regardless of which elements
+ you use, give each structural element a unique id, so that
+ you can link to it. For usage example, see the template.
+ </p>
+<p> Please try to avoid using deeply nested sections; for
+ most situations, <tt><sect1></tt> and
+ <tt><sect2></tt> should be sufficient. If not,
+ you probably should split your <tt><sect1></tt>
+ into several smaller ones.
+ </p>
+<p> Use the tag <tt><para></tt> for
+ paragraphs, even if there is only one paragraph in a
+ section--see template for examples.
+ </p>
+</div>
+<div class="sect3">
+<a name="notes"></a><div class="titlepage"><div><h4 class="title">
+<a name="notes"></a>Notes, Warnings, And Tips</h4></div></div>
+<p>
+ For notes, tips, warnings, and important information, which
+ should be set apart from the main text (usually as a
+ paragraph with some warning sign on the margin), use tags
+ <tt><note></tt>, <tt><tip></tt>,
+ <tt><warning></tt>,
+ <tt><important></tt> respectively. For example:
+ <pre class="programlisting">
+
+<tip>
+ <title>TIP</title>
+ <para>
+ To speed up program compilation, use <application>gcc</application>
+ compiler with Pentium optimization.
+ </para>
+</tip> </pre> produces
+ </p>
+<div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;">
+<h3 class="title">
+<a name="extip"></a>TIP</h3>
+<p>
+ To speed up program compilation, use
+ gcc compiler with Pentium
+ optimization. </p>
+</div>
+<p>
+ Note that this should not be inside a
+ <tt><para></tt> but between paragraphs.
+ </p>
+</div>
+<div class="sect3">
+<a name="figures"></a><div class="titlepage"><div><h4 class="title">
+<a name="figures"></a> Screenshots and other figures</h4></div></div>
+<p>
+ To include screenshots and other figures, use the following
+ tags:
+
+ <pre class="programlisting">
+
+<figure id="shot1">
+ <title>Screenshot</title>
+ <screenshot>
+ <screeninfo>Screenshot of a program</screeninfo>
+ <graphic format="PNG" fileref="figures/example_screenshot" srccredit="ME">
+ </graphic>
+ </screenshot>
+</figure>
+ </pre>
+ replacing <tt>example_screenshot</tt> with the
+ actual file name (without extension). The result will look like this:
+
+ <div class="figure">
+<p>
+<a name="shot1"></a><b>Figure 1. Screenshot</b>
+</p>
+<div class="screenshot"><p><img src="figures/example_screenshot"></p></div>
+</div>
+ </p>
+<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
+<h3 class="title">
+<a name="id2905651"></a>NOTE</h3>
+<p>
+ Notice in this example that the screenshot file name does
+ not include the file type extension -- to find out
+ why, please read <a href="indexs02.html#jadeimages" title="Images in DocBook Tools">the section called “Images in DocBook Tools”</a>.
+ </p>
+</div>
+</div>
+<div class="sect3">
+<a name="listing"></a><div class="titlepage"><div><h4 class="title">
+<a name="listing"></a>Program listings and terminal session</h4></div></div>
+<p>
+ To show a file fragment--for example, program
+ listing--use <tt><programlisting></tt> tag:
+ <pre class="programlisting">
+
+<programlisting>
+[Desktop Entry]
+Name=Gnumeric spreadsheet
+Exec=gnumeric
+Icon=gnome-gnumeric.png
+Terminal=0
+Type=Application
+</programlisting>
+ </pre>
+ which produces
+ <pre class="programlisting">
+[Desktop Entry]
+Name=Gnumeric spreadsheet
+Exec=gnumeric
+Icon=gnome-gnumeric.png
+Terminal=0
+Type=Application
+ </pre>
+ As a matter of fact, all examples in this document were
+ produced using <tt><programlisting></tt>.
+ </p>
+<p>
+ To show a record of terminal session--i.e., sequence of
+ commands entered at the command line--use
+ <tt><screen></tt> tag:
+ <pre class="programlisting">
+
+<screen>
+<prompt>bash$</prompt><userinput>make love</userinput>
+make: *** No rule to make target `love'. Stop.
+</screen>
+ </pre>
+ which produces
+ <pre class="screen">
+<tt>bash$</tt><b><tt>make love</tt></b>
+make: *** No rule to make target `love'. Stop.
+ </pre>
+ Note the use of tags <tt><prompt></tt> and
+ <tt><userinput></tt> for marking system prompt
+ and commands entered by user.
+ <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
+<h3 class="title">
+<a name="id2905863"></a>NOTE</h3>
+<p>
+ Note that both <tt><programlisting></tt>
+ and <tt><screen></tt> preserve linebreaks,
+ but interpret SGML tags (unlike LaTeX
+ verbatim environment). Take a look at
+ the source of this document to see how you can have SGML
+ tags literally shown but not interpreted,
+ </p>
+</div>
+ </p>
+</div>
+<div class="sect3">
+<a name="lists"></a><div class="titlepage"><div><h4 class="title">
+<a name="lists"></a> Lists</h4></div></div>
+<p>
+ The most common list types in DocBook are
+ <tt><itemizedlist></tt>,
+ <tt><orderedlist></tt>, and
+ <tt><variablelist></tt>.
+ </p>
+<div class="variablelist"><dl>
+<dt>
+<a name="id2905982"></a><span class="term"> <tt><itemizedlist></tt></span>
+</dt>
+<dd>
+<p>
+<a name="id2906002"></a>
+ This is the simplest unnumbered list, parallel to
+ <tt><ul></tt> in HTML. Here is an example:
+ <pre class="programlisting">
+
+<itemizedlist>
+ <listitem>
+ <para>
+ <guilabel>Show backup files</guilabel> &mdash; This will
+ show any backup file that might be on your system.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <guilabel>Show hidden files</guilabel> &mdash; This will
+ show all "dot files" or files that begin with a dot. This
+ files typically include configuration files and directories.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <guilabel>Mix files and directories</guilabel> &mdash; This
+ option will display files and directories in the order you
+ sort them instead of
+ always having directories shown above files.
+ </para>
+ </listitem>
+</itemizedlist>
+
+ </pre>
+ and output:
+ </p>
+<div class="itemizedlist"><ul>
+<li><p>
+<a name="id2906020"></a>
+ Show backup files --
+ This will show any backup file that might be on
+ your system.
+ </p></li>
+<li><p>
+<a name="id2906082"></a>
+ Show hidden files --
+ This will show all "dot files" or files that
+ begin with a dot. This files typically include
+ configuration files and directories.
+ </p></li>
+<li><p>
+<a name="id2906109"></a>
+ Mix files and directories
+ -- This option will display files and
+ directories in the order you sort them instead
+ of always having directories shown above files.
+ </p></li>
+</ul></div>
+<p> Note the use of <tt>&mdash;</tt>
+ for long dash (see <a href="indexs04.html#specsymb" title=" Special symbols ">the section called “ Special symbols ”</a>). Also,
+ please note that the result looks much nicer because the
+ terms being explained (Show backup
+ files, etc.) are set in a different font. In
+ this case, it was achieved by using <a href="indexs04.html#gui" title="GUI elements"><tt><guilabel></tt></a>
+ tag. In other cases, use appropriate tags such as
+ <a href="indexs04.html#gui" title="GUI elements"><tt><guimenuitem></tt></a>,
+ <a href="indexs04.html#filenames" title="Filenames, commands, and other
+ computer-related things"><tt><command></tt></a>,
+ or -- if none of
+ this applies -- use
+ <a href="indexs04.html#gui" title="GUI elements"><tt><emphasis></tt></a>.
+ </p>
+</dd>
+<dt>
+<a name="id2906276"></a><span class="term"> <tt><orderedlist></tt></span>
+</dt>
+<dd><p>
+<a name="id2906294"></a>
+ This list is completely analogous to
+ <tt><itemizedlist></tt> and has the same
+ syntax, but it produces numbered list. By default,
+ this list uses Arabic numerals for numbering entries;
+ you can override this using <tt>numeration</tt>,
+ for example <tt><orderedlist
+ numeration="lowerroman"></tt>. Possible values of
+ these attribute are <tt>arabic</tt>,
+ <tt>upperalpha</tt>,
+ <tt>loweralpha</tt>,
+ <tt>upperroman</tt>,
+ <tt>lowerroman</tt>.
+ </p></dd>
+<dt>
+<a name="id2906374"></a><span class="term"> <tt><variablelist></tt></span>
+</dt>
+<dd><p>
+<a name="id2906394"></a> This list is used when each entry is
+ rather long, so it should be formatted as a block of text
+ with some subtitle, like a small subsection. The
+ <tt><variablelist></tt> is more complicated
+ than itemizedlists, but for larger blocks of text, or when
+ you're explaining or defining something, it's best to use
+ them. Their greatest advantage is that it's easier for a
+ computer to search. The lines you are reading now were
+ produced by <tt><variablelist></tt>. The
+ source looked liked this:
+ <pre class="programlisting">
+
+<variablelist>
+ <varlistentry>
+ <term> <sgmltag>&lt;itemizedlist></sgmltag></term>
+ <listitem><para>
+ This is the simplest unnumbered list, parallel to
+ <sgmltag>&lt;ul></sgmltag> in HTML. Here is an example:...
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term> <sgmltag>&lt;orderedlist></sgmltag></term>
+ <listitem><para>
+ This list is completely analogous to
+ <sgmltag>&lt;itemizedlist></sgmltag>
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term> <sgmltag>&lt;variablelist></sgmltag></term>
+ <listitem><para>
+ This list is used when each entry is rather long,...
+ </para></listitem>
+ </varlistentry>
+</variablelist>
+
+ </pre>
+ </p></dd>
+</dl></div>
+<p>
+ Lists can be nested; in this case, the stylesheets
+ are smart enough to change the numeration (for
+ <tt><orderedlist></tt>) or marks of each entry
+ (in <tt><itemizedlist></tt>) for sub-lists
+ </p>
+</div>
+</div>
+<div class="sect2">
+<a name="inline"></a><div class="titlepage"><div><h3 class="title">
+<a name="inline"></a>Inline Elements</h3></div></div>
+<div class="sect3">
+<a name="gui"></a><div class="titlepage"><div><h4 class="title">
+<a name="gui"></a>GUI elements</h4></div></div>
+<div class="itemizedlist"><ul>
+<li><p>
+<a name="id2906551"></a>
+ <tt><guibutton></tt> -- used for
+ buttons, including checkbuttons and radio buttons
+ </p></li>
+<li><p>
+<a name="id2906577"></a>
+ <tt><guimenu></tt>,
+ <tt><guisubmenu></tt> --used for
+ top-level menus and submenus
+ respectively, for example <tt>
+ <guisubmenu>Utilities</guisubmenu> submenu of the
+ <guimenu>Main Menu</guimenu></tt>
+ </p></li>
+<li><p>
+<a name="id2906621"></a>
+ <tt><guimenuitem></tt>--an entry in a
+ menu
+ </p></li>
+<li><p>
+<a name="id2906647"></a>
+ <tt><guiicon></tt>--an icon
+ </p></li>
+<li><p>
+<a name="id2906671"></a>
+ <tt><guilabel></tt>--for items which have
+ labels, like tabs, or bounding boxes.
+ </p></li>
+<li><p>
+<a name="id2906696"></a>
+ <tt><interface></tt>-- for most everything
+ else... a window, a dialog box, the Panel, etc.
+ </p></li>
+</ul></div>
+<p>
+ If you need to refer to a sequence of menu choices, such as
+ Main Menu->Utilities->GNOME
+ terminal
+ there is a special construction for this, too:
+ <pre class="programlisting">
+
+<menuchoice>
+ <guimenu>Main Menu</guimenu> <guisubmenu>Utilities</guisubmenu>
+ <guimenuitem>GNOME terminal</guimenuitem> </menuchoice>
+ </pre>
+ </p>
+</div>
+<div class="sect3">
+<a name="links"></a><div class="titlepage"><div><h4 class="title">
+<a name="links"></a>Links and references</h4></div></div>
+<p>
+ To refer to another place in the same document, you can use
+ tags <tt><xref></tt> and
+ <tt><link></tt>. The first of them
+ automatically inserts the full name of the element you refer
+ to (section, figure, etc.), while the second just creates a
+ link (in HTML output). Here is an example:
+ <pre class="programlisting">
+An example of a <link linkend="extip">tip</link> was given in
+<xref linkend="notes" />.
+ </pre>
+ which produces: An example of a <a href="indexs04.html#extip">tip</a> was given in <a href="indexs04.html#notes" title="Notes, Warnings, And Tips">the section called “Notes, Warnings, And Tips”</a>.
+ </p>
+<p>
+ Here <tt>notes</tt> and <tt>extip</tt>
+ are the id attributes of <a href="indexs04.html#notes" title="Notes, Warnings, And Tips">the section called “Notes, Warnings, And Tips”</a> and of the
+ example of a tip in it.
+ </p>
+<p> To produce a link to an external source, such as a
+ Web page or a local file, use <tt><ulink></tt>
+ tag, for example:
+ <pre class="programlisting">
+ To find more about GNOME, please visit <ulink type="http"
+url="http://www.gnome.org">GNOME Web page</ulink>
+ </pre>
+ which produces: To find more about GNOME, please visit
+ <a href="http://www.gnome.org" target="_top">The GNOME Web
+ Site</a> You can use any of the standard URL types, such
+ as <tt>http, ftp, file, telnet, mailto</tt> (in
+ most cases, however, use of <tt>mailto</tt> is
+ unnecessary--see discussion of
+ <tt><email></tt> tag).
+ </p>
+</div>
+<div class="sect3">
+<a name="filenames"></a><div class="titlepage"><div><h4 class="title">
+<a name="filenames"></a>Filenames, commands, and other
+ computer-related things</h4></div></div>
+<p>
+ Here are some tags used to describe operating system-related
+ things:
+ </p>
+<div class="itemizedlist"><ul>
+<li><p>
+<a name="id2907053"></a> <tt><filename></tt> -- used
+ for filenames,
+ e.g.<tt><filename></tt>
+ foo.sgml
+ <tt></filename></tt>
+ produces: <tt>foo.sgml</tt>.
+ </p></li>
+<li><p>
+<a name="id2907102"></a> <tt><filename
+ class="directory"></tt> -- used for
+ directories, e.g.<tt><filename
+ class="directory"></tt>/usr/bin
+ <tt></filename></tt>
+ produces: <tt>/usr/bin</tt>.
+ </p></li>
+<li><p>
+<a name="id2907159"></a>
+ <tt><application></tt> -- used for
+ application names,
+ e.g. <tt><application></tt>Gnumeric
+ <tt></application></tt> produces:
+ Gnumeric.
+ </p></li>
+<li><p>
+<a name="id2907209"></a>
+ <tt><envar></tt> -- used for
+ environment variables, e.g.
+ <tt><envar></tt>PATH<tt></envar></tt>.
+ </p></li>
+<li><p>
+<a name="id2907250"></a>
+ <tt><command></tt> -- used for
+ commands entered on command line, e.g.
+ <tt><command></tt>make install
+ <tt></command></tt> produces:
+ <b>make install</b>.
+ </p></li>
+<li><p>
+<a name="id2907299"></a>
+ <tt><replaceable></tt> -- used for
+ replaceable text, e.g.
+ <tt><command></tt>db2html<tt><replaceable></tt>
+ foo.sgml
+ <tt></replaceable></tt><tt></command></tt>
+ produces: <b>db2html
+ <i><tt>foo.sgml</tt></i></b>.
+ </p></li>
+</ul></div>
+</div>
+<div class="sect3">
+<a name="keys"></a><div class="titlepage"><div><h4 class="title">
+<a name="keys"></a>Keyboard input</h4></div></div>
+<p> To mark up text input by the user, use
+ <tt><userinput></tt>.
+ </p>
+<p> To mark keystrokes such as shortcuts and other
+ commands, use <tt><keycap></tt>.
+ This is used for marking up what is printed on the top
+ of the physical key on the keyboard. There are a couple of
+ other tags for keys, too: <tt><keysym></tt>
+ and <tt><keycode></tt>. However you are
+ unlikely to need these for most documentation. For reference,
+ <tt><keysym></tt> is for the ‘symbolic
+ name’ of a key. <tt><keycode></tt> is
+ for the ‘scan code’ of a key. These are not
+ terms commonly required in GNOME documentation,
+ although <tt><keysym></tt> is useful for marking
+ up control codes.
+ </p>
+<p>
+ To mark up a combination of keystrokes, use the
+ <tt><keycombo></tt> wrapper:
+ <pre class="programlisting">
+
+<keycombo>
+ <keycap>Ctrl</keycap>
+ <keycap>Alt</keycap>
+ <keycap>F1</keycap>
+</keycombo>
+ </pre>
+ </p>
+<p>
+ Finally, if you want to show a shortcut for some menu
+ command, here are the appropriate tags (rather long):
+ <pre class="programlisting">
+
+<menuchoice>
+ <shortcut>
+ <keycombo><keycap>Ctrl</keycap><keycap>q</keycap></keycombo>
+ </shortcut>
+ <guimenuitem> Quit</guimenuitem>
+</menuchoice>
+ </pre>
+ which produces simply
+ Quit (<b>Ctrl-q</b>)
+ </p>
+</div>
+<div class="sect3">
+<a name="email"></a><div class="titlepage"><div><h4 class="title">
+<a name="email"></a>E-mail addresses</h4></div></div>
+<p> To mark up e-mail
+ address, use <tt><email></tt>:
+ <pre class="programlisting">
+ The easiest way to get in touch with me is by e-mail
+(<email>me@mydomain.com</email>)
+ </pre>
+ which produces: The easiest way to get in touch with me is
+ by e-mail (<tt><<a href="mailto:me@mydomain.com">me@mydomain.com</a>></tt>) Note that
+ <tt><email></tt> automatically produces a link
+ in html version.
+ </p>
+</div>
+<div class="sect3">
+<a name="specsymb"></a><div class="titlepage"><div><h4 class="title">
+<a name="specsymb"></a> Special symbols </h4></div></div>
+<p>
+ DocBook also provides special means for entering
+ typographic symbols which can not be entered directly
+ form the keyboard (such as copyright sign). This is done using
+ <i>entities</i>, which is SGML analogue of
+ macros, or commands, of LaTeX. They generally have the form
+ <tt>&entityname;</tt>. Note that the semicolon
+ is required.
+ </p>
+<p>
+ here is partial list of most commonly used enitites:
+ </p>
+<div class="itemizedlist"><ul>
+<li><p>
+<a name="id2907739"></a>
+ <tt>&amp;</tt> -- ampersend (&)
+ </p></li>
+<li><p>
+<a name="id2907758"></a>
+ <tt>&lt;</tt> -- left angle bracket (<)
+ </p></li>
+<li><p>
+<a name="id2907777"></a>
+ <tt>&copy;</tt> -- copyright sign (©)
+ </p></li>
+<li><p>
+<a name="id2907796"></a>
+ <tt>&mdash;</tt> -- long dash (--)
+ </p></li>
+<li><p>
+<a name="id2907815"></a>
+ <tt>&hellip;</tt> -- ellipsis (...)
+ </p></li>
+</ul></div>
+<p>
+ Note that the actual look of the resulting symbols depends
+ on the fonts used by your browser; for example, it might
+ happen that long dash (<tt>&mdash;</tt>) looks
+ exactly like the usual dash (-). However, in the PostScript
+ (and thus, in print) the output will look markedly better if
+ you use appropriate tags.
+ </p>
+</div>
+</div>
+</div>
+<div class="navfooter">
+<hr>
+<table width="100%" summary="Navigation footer">
+<tr>
+<td width="40%" align="left">
+<a href="indexs03.html">Prev</a> </td>
+<td width="20%" align="center"><a href="index.html">Home</a></td>
+<td width="40%" align="right"> <a href="indexs05.html">Next</a>
+</td>
+</tr>
+<tr>
+<td width="40%" align="left">The GNOME Documentation System </td>
+<td width="20%" align="center"><a href="index.html">Up</a></td>
+<td width="40%" align="right"> GDP Documentation Conventions </td>
+</tr>
+</table>
+</div>
+</body>
+</html>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
+<html>
+<head>
+<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
+<title>GDP Documentation Conventions </title>
+<meta name="generator" content="DocBook XSL Stylesheets V1.40">
+<link rel="home" href="index.html" title="The GNOME Handbook of Writing Software Documentation">
+<link rel="up" href="index.html" title="The GNOME Handbook of Writing Software Documentation">
+<link rel="previous" href="indexs04.html" title="DocBook Basics ">
+<link rel="next" href="indexs06.html" title="Writing Application and Applet Manuals">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<div class="navheader">
+<table width="100%" summary="Navigation header">
+<tr><th colspan="3" align="center">GDP Documentation Conventions </th></tr>
+<tr>
+<td width="20%" align="left">
+<a href="indexs04.html">Prev</a> </td>
+<th width="60%" align="center"> </th>
+<td width="20%" align="right"> <a href="indexs06.html">Next</a>
+</td>
+</tr>
+</table>
+<hr>
+</div>
+<div class="sect1">
+<a name="conventions"></a><div class="titlepage"><div><h2 class="title" style="clear: both">
+<a name="conventions"></a>GDP Documentation Conventions </h2></div></div>
+<div class="sect2">
+<a name="conventionsalldocs"></a><div class="titlepage"><div><h3 class="title">
+<a name="conventionsalldocs"></a>Conventions for All GDP Documentation</h3></div></div>
+<div class="sect3">
+<a name="xmlcomp"></a><div class="titlepage"><div><h4 class="title">
+<a name="xmlcomp"></a> XML compatibility </h4></div></div>
+<p>
+ All GNOME documentation should conform to XML syntax
+ requirements, which are stricter than SGML ones -- see
+ <a href="indexs04.html#xml" title="XML and SGML">the section called “XML and SGML”</a> for more informaion.
+ </p>
+</div>
+<div class="sect3">
+<a name="authorsnames"></a><div class="titlepage"><div><h4 class="title">
+<a name="authorsnames"></a> Authors' names</h4></div></div>
+<p>
+ All GNOME documentation should contain the names of both the
+ application authors and documentation authors, as well as a
+ link to the application web page (if it exists) and
+ information for bug submission -- see templates for an
+ example.
+ </p>
+</div>
+</div>
+<div class="sect2">
+<a name="conventionsappdocs"></a><div class="titlepage"><div><h3 class="title">
+<a name="conventionsappdocs"></a>Conventions for Application Documentation</h3></div></div>
+<div class="sect3">
+<a name="applicationversionid"></a><div class="titlepage"><div><h4 class="title">
+<a name="applicationversionid"></a>Application Version Identification</h4></div></div>
+<p>
+ Application documentation should identify the version of the
+ application for which the documentation is written:
+ <pre class="programlisting">
+
+<sect1 id="intro">
+ <title>Introduction</title>
+ <para>
+ blah-blah-blah This document describes version 1.0.53 of gfoo.
+ </para>
+</sect1>
+ </pre>
+ </p>
+</div>
+<div class="sect3">
+<a name="license"></a><div class="titlepage"><div><h4 class="title">
+<a name="license"></a> Copyright information </h4></div></div>
+<p> Application
+ documentation should contain a copyright notice, stating the
+ licensing terms. It is suggested that you use the GNU Free
+ Documentation License. You could also use some other license
+ allowing free redistribution, such as GPL or Open Content
+ license. If documentation uses some trademarks (such as UNIX,
+ Linux, Windows, etc.), proper legal junk should also be
+ included (see templates).
+ </p>
+</div>
+<div class="sect3">
+<a name="license2"></a><div class="titlepage"><div><h4 class="title">
+<a name="license2"></a>Software license</h4></div></div>
+<p>
+ All GNOME applications must contain information about the
+ license (for software, not for documentation), either in the
+ "About" box or in the manual.
+ </p>
+</div>
+<div class="sect3">
+<a name="bugtraq"></a><div class="titlepage"><div><h4 class="title">
+<a name="bugtraq"></a> Bug reporting</h4></div></div>
+<p>
+ Application documentation should give an address for
+ reporting bugs and for submitting comments about the
+ documentaion (see templates for an example).
+ </p>
+</div>
+</div>
+</div>
+<div class="navfooter">
+<hr>
+<table width="100%" summary="Navigation footer">
+<tr>
+<td width="40%" align="left">
+<a href="indexs04.html">Prev</a> </td>
+<td width="20%" align="center"><a href="index.html">Home</a></td>
+<td width="40%" align="right"> <a href="indexs06.html">Next</a>
+</td>
+</tr>
+<tr>
+<td width="40%" align="left">DocBook Basics </td>
+<td width="20%" align="center"><a href="index.html">Up</a></td>
+<td width="40%" align="right"> Writing Application and Applet Manuals</td>
+</tr>
+</table>
+</div>
+</body>
+</html>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
+<html>
+<head>
+<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
+<title>Writing Application and Applet Manuals</title>
+<meta name="generator" content="DocBook XSL Stylesheets V1.40">
+<link rel="home" href="index.html" title="The GNOME Handbook of Writing Software Documentation">
+<link rel="up" href="index.html" title="The GNOME Handbook of Writing Software Documentation">
+<link rel="previous" href="indexs05.html" title="GDP Documentation Conventions ">
+<link rel="next" href="indexs07.html" title="Listing Documents in the Help Menu">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<div class="navheader">
+<table width="100%" summary="Navigation header">
+<tr><th colspan="3" align="center">Writing Application and Applet Manuals</th></tr>
+<tr>
+<td width="20%" align="left">
+<a href="indexs05.html">Prev</a> </td>
+<th width="60%" align="center"> </th>
+<td width="20%" align="right"> <a href="indexs07.html">Next</a>
+</td>
+</tr>
+</table>
+<hr>
+</div>
+<div class="sect1">
+<a name="writingapplicationmanuals"></a><div class="titlepage"><div><h2 class="title" style="clear: both">
+<a name="writingapplicationmanuals"></a>Writing Application and Applet Manuals</h2></div></div>
+<p>
+ Every GNOME application or applet should have a manual specific
+ to that particular application. This manual should be a complete
+ and authoritative guide. The manual should describe what the
+ program does and how to use it. Manuals will typically describe
+ each window or panel presented to the user using screenshots (in
+ PNG format only) when appropriate. They should also describe
+ each feature and preference option available.
+ </p>
+<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
+<h3 class="title">
+<a name="id2908273"></a>Documentation Availability</h3>
+<p>
+ Applications and applets should not rely on documentation
+ which is only available on the internet. All manuals and
+ other documentation should be packaged with the application or
+ applet and be made available to the user through the standard
+ GNOME help system methods described below.
+ </p>
+</div>
+<p> Application manuals should be based on the template in
+ <a href="apa.html#template1" title="Template 1: Application Manual">the section called “Template 1: Application Manual”</a>. Applet manuals should be based on
+ the templates in <a href="apas17.html" title="Template 2: Applet Manual For GNOME 1.x">the section called “Template 2: Applet Manual For GNOME 1.x”</a> for GNOME
+ versions 1.x and the templates in <a href="apas18.html" title="Template 2: Applet Manual For GNOME 2.x">the section called “Template 2: Applet Manual For GNOME 2.x”</a>
+ for GNOME versions 2.x.
+ </p>
+<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
+<h3 class="title">
+<a name="id2908313"></a>Manuals For Large Applications</h3>
+<p>
+ Manuals for very large applications, such as GNOME Workshop
+ components should be a <tt><book></tt> (and thus
+ use <tt><chapter></tt> for each primary section)
+ , instead of <tt><article></tt> which most
+ applications use(with each primary section being a
+ <tt><sect1></tt>).
+ </p>
+</div>
+<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
+<h3 class="title">
+<a name="id2908428"></a>Applet Manuals in GNOME 2.0</h3>
+<p>
+ Note that applet manuals in GNOME 2.0 are treated in a special
+ way. The manuals for all applets are merged into a single
+ virtual document by Nautilus. For this reason, the header
+ information for applet manuals is omitted and the first
+ section of each applet is
+ <tt><sect1></tt>. Applet manuals will typically
+ have several sections, each of which is
+ <tt><sect2></tt>.
+ </p>
+</div>
+<p>
+ Application manuals should be made available by having a
+ "Manual" entry in the Help pull-down menu
+ at the top of the
+ application, as described in <a href="indexs07.html" title="Listing Documents in the Help Menu">the section called “Listing Documents in the Help Menu”</a>.
+ Applets should make their manuals available by
+ right-clicking on the applet.
+ </p>
+</div>
+<div class="navfooter">
+<hr>
+<table width="100%" summary="Navigation footer">
+<tr>
+<td width="40%" align="left">
+<a href="indexs05.html">Prev</a> </td>
+<td width="20%" align="center"><a href="index.html">Home</a></td>
+<td width="40%" align="right"> <a href="indexs07.html">Next</a>
+</td>
+</tr>
+<tr>
+<td width="40%" align="left">GDP Documentation Conventions </td>
+<td width="20%" align="center"><a href="index.html">Up</a></td>
+<td width="40%" align="right"> Listing Documents in the Help Menu</td>
+</tr>
+</table>
+</div>
+</body>
+</html>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
+<html>
+<head>
+<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
+<title>Listing Documents in the Help Menu</title>
+<meta name="generator" content="DocBook XSL Stylesheets V1.40">
+<link rel="home" href="index.html" title="The GNOME Handbook of Writing Software Documentation">
+<link rel="up" href="index.html" title="The GNOME Handbook of Writing Software Documentation">
+<link rel="previous" href="indexs06.html" title="Writing Application and Applet Manuals">
+<link rel="next" href="indexs08.html" title="Application Help Buttons">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<div class="navheader">
+<table width="100%" summary="Navigation header">
+<tr><th colspan="3" align="center">Listing Documents in the Help Menu</th></tr>
+<tr>
+<td width="20%" align="left">
+<a href="indexs06.html">Prev</a> </td>
+<th width="60%" align="center"> </th>
+<td width="20%" align="right"> <a href="indexs08.html">Next</a>
+</td>
+</tr>
+</table>
+<hr>
+</div>
+<div class="sect1">
+<a name="listingdocsinhelpmenu"></a><div class="titlepage"><div><h2 class="title" style="clear: both">
+<a name="listingdocsinhelpmenu"></a>Listing Documents in the Help Menu</h2></div></div>
+<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
+<h3 class="title">
+<a name="id2908546"></a>Developer Information</h3>
+<p>
+ This section is for developers. Documentation authors
+ generally do not need to know this material.
+ </p>
+</div>
+<p>
+ Typically the application manual and possibly additional help
+ documents will be made available to the user under the
+ Help menu at the top right of the
+ application. To do this, you must first write a
+ <tt>topic.dat</tt> file. The format for this file is:
+ <pre class="programlisting">
+One line for each 'topic'.
+
+Two columns, as defined by perl -e 'split(/\s+/,$aline,2)'
+
+First column is the HTML file (and optional section) for the topic,
+relative to the app's help file dir.
+
+Second column is the user-visible topic name.
+ </pre>
+ For example, Gnumeric's
+ <tt>topic.dat</tt> file is:
+ <pre class="programlisting">
+gnumeric.html Gnumeric manual
+function-reference.html Gnumeric function reference
+ </pre>
+ When the application is installed, the
+ <tt>topic.dat</tt> file should be placed in the
+ <tt>$prefix/share/gnome/help/<i><tt>appname</tt></i>/C/</tt> directory
+ where <i><tt>appname</tt></i> is replaced by the
+ application's name. The application documentation (converted
+ from SGML into HTML with <b>db2html</b>) should be
+ placed in this directory too.
+ </p>
+<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
+<h3 class="title">
+<a name="id2908690"></a>Note</h3>
+<p>
+ If the help files are not present in the correct directory, the
+ menu items will NOT appear when the program is run.
+ </p>
+</div>
+<p>
+ The <tt>topic.dat</tt> file is used by the GNOME
+ menu building code to generate the Help
+ menu. When you define your menu:
+<pre class="programlisting">
+GnomeUIInfo helpmenu[] = {
+ {GNOME_APP_UI_ITEM,
+ N_("About"), N_("Info about this program"),
+ about_cb, NULL, NULL,
+ GNOME_APP_PIXMAP_STOCK, GNOME_STOCK_MENU_ABOUT,
+ 0, 0, NULL},
+ GNOMEUIINFO_SEPARATOR,
+ GNOMEUIINFO_HELP("<i>appname</i>"),
+ GNOMEUIINFO_END
+ };
+</pre>
+ the line specifying <tt>GNOMEUIINFO_HELP</tt> causes
+ GNOME to create a menu entry which is tied to the documentation
+ in the directory mentioned above. Also, all the topics in the
+ <tt>topic.dat</tt> file will get menu entries in the
+ Help menu. When the user selects any of these
+ topics from the Help menu, a help browser
+ will be started with the associated HTML documentation.
+ </p>
+</div>
+<div class="navfooter">
+<hr>
+<table width="100%" summary="Navigation footer">
+<tr>
+<td width="40%" align="left">
+<a href="indexs06.html">Prev</a> </td>
+<td width="20%" align="center"><a href="index.html">Home</a></td>
+<td width="40%" align="right"> <a href="indexs08.html">Next</a>
+</td>
+</tr>
+<tr>
+<td width="40%" align="left">Writing Application and Applet Manuals </td>
+<td width="20%" align="center"><a href="index.html">Up</a></td>
+<td width="40%" align="right"> Application Help Buttons</td>
+</tr>
+</table>
+</div>
+</body>
+</html>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
+<html>
+<head>
+<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
+<title>Application Help Buttons</title>
+<meta name="generator" content="DocBook XSL Stylesheets V1.40">
+<link rel="home" href="index.html" title="The GNOME Handbook of Writing Software Documentation">
+<link rel="up" href="index.html" title="The GNOME Handbook of Writing Software Documentation">
+<link rel="previous" href="indexs07.html" title="Listing Documents in the Help Menu">
+<link rel="next" href="indexs09.html" title="Packaging Applet Documentation">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<div class="navheader">
+<table width="100%" summary="Navigation header">
+<tr><th colspan="3" align="center">Application Help Buttons</th></tr>
+<tr>
+<td width="20%" align="left">
+<a href="indexs07.html">Prev</a> </td>
+<th width="60%" align="center"> </th>
+<td width="20%" align="right"> <a href="indexs09.html">Next</a>
+</td>
+</tr>
+</table>
+<hr>
+</div>
+<div class="sect1">
+<a name="applicationhelpbuttons"></a><div class="titlepage"><div><h2 class="title" style="clear: both">
+<a name="applicationhelpbuttons"></a>Application Help Buttons</h2></div></div>
+<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
+<h3 class="title">
+<a name="id2908827"></a>Developer Information</h3>
+<p>
+ This section is for developers. Documentation authors
+ generally do not need to know this material.
+ </p>
+</div>
+<p>
+ Most GNOME applications will have Help
+ buttons. These are most often seen in Preference windows. (All
+ Preference windows should have Help
+ buttons.) Most Help buttons will connect
+ to the application manual, although some may connect to special
+ documents. Because the Help buttons do
+ not generally have their own special documentation, the
+ documentation author(s) do not need to do very much. However,
+ the application author must be careful to guarantee that the
+ application correctly opens the help documentation when the
+ Help buttons are pressed.
+ </p>
+<p>
+ To make the Help buttons call the correct document in the GNOME Help
+ Browser the developer should add code based on the following example:
+ </p>
+<pre class="programlisting">
+gchar *tmp;
+tmp = gnome_help_file_find_file ("module", "page.html");
+if (tmp) {
+ gnome_help_goto(0, tmp);
+ g_free(tmp);
+}
+ </pre>
+<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
+<h3 class="title">
+<a name="id2908933"></a>NOTE</h3>
+<p>
+ The example above is in the C language, please refer to other
+ documentation or forums for other GNOME language bindings.
+ </p>
+</div>
+</div>
+<div class="navfooter">
+<hr>
+<table width="100%" summary="Navigation footer">
+<tr>
+<td width="40%" align="left">
+<a href="indexs07.html">Prev</a> </td>
+<td width="20%" align="center"><a href="index.html">Home</a></td>
+<td width="40%" align="right"> <a href="indexs09.html">Next</a>
+</td>
+</tr>
+<tr>
+<td width="40%" align="left">Listing Documents in the Help Menu </td>
+<td width="20%" align="center"><a href="index.html">Up</a></td>
+<td width="40%" align="right"> Packaging Applet Documentation</td>
+</tr>
+</table>
+</div>
+</body>
+</html>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
+<html>
+<head>
+<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
+<title>Packaging Applet Documentation</title>
+<meta name="generator" content="DocBook XSL Stylesheets V1.40">
+<link rel="home" href="index.html" title="The GNOME Handbook of Writing Software Documentation">
+<link rel="up" href="index.html" title="The GNOME Handbook of Writing Software Documentation">
+<link rel="previous" href="indexs08.html" title="Application Help Buttons">
+<link rel="next" href="indexs10.html" title="Writing Context Sensitive Help (coming in GNOME-2.0)">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<div class="navheader">
+<table width="100%" summary="Navigation header">
+<tr><th colspan="3" align="center">Packaging Applet Documentation</th></tr>
+<tr>
+<td width="20%" align="left">
+<a href="indexs08.html">Prev</a> </td>
+<th width="60%" align="center"> </th>
+<td width="20%" align="right"> <a href="indexs10.html">Next</a>
+</td>
+</tr>
+</table>
+<hr>
+</div>
+<div class="sect1">
+<a name="packagingappletdocs"></a><div class="titlepage"><div><h2 class="title" style="clear: both">
+<a name="packagingappletdocs"></a>Packaging Applet Documentation</h2></div></div>
+<div class="sect2">
+<a name="appletfiles"></a><div class="titlepage"><div><h3 class="title">
+<a name="appletfiles"></a>Applet Documentation Files</h3></div></div>
+<p>
+ In GNOME 2.0 each applet will have its own documentation
+ installed separately, and the GNOME 2.0 help
+ browser (Nautilus) will dynamically
+ merge the applet documents into a single virtual book
+ called <i>GNOME Applets</i>. During the
+ transitionary stage between GNOME 1.0 and GNOME 2.0, each
+ applet in the gnome-applets package has its own manual(stored
+ with the applet in CVS), but they are merged together manually
+ to create the <i>GNOME Applets</i> book before
+ distribution. Telsa
+ <tt><<a href="mailto:hobbit@aloss.ukuu.org.uk">hobbit@aloss.ukuu.org.uk</a>></tt> is the maintainer of
+ this document. Applet documentation should be sent to Telsa
+ (or placed in CVS) who will make sure they are correctly
+ packaged with the applets. The applet author should be
+ contacted to modify the menu items and help buttons to bind to
+ the applet documentation if necessary.
+ </p>
+<p>
+ Images which are part of the applet documentation should be in
+ PNG format and should reside in the same directory as the SGML
+ document file in CVS(gnome-applets/APPLETNAME/help/C).
+ </p>
+<p>
+ Applets which are not part of the gnome-applets package must
+ package their documentation with the particular applet
+ package. They should use the same applet template as other
+ applets. However, the <tt><xref></tt> links to
+ the introductory chapter of the <i>GNOME
+ Applets</i> book must be removed (as the 1.x
+ GNOME Help Browser does not allow
+ you to create links between separate documents) and replaced
+ with suitable text. Note that since this document is not part
+ of the <i>GNOME Applets</i> book, you must
+ remember to add <tt><legalnotice></tt> and
+ <tt><copyright></tt> sections.
+ </p>
+</div>
+<div class="sect2">
+<a name="appletmenu"></a><div class="titlepage"><div><h3 class="title">
+<a name="appletmenu"></a>Adding Documentation to an Applet Menu</h3></div></div>
+<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
+<h3 class="title">
+<a name="id2909175"></a>Developer Information</h3>
+<p>
+ This section is for developers. Documentation authors
+ generally do not need to know this material.
+ </p>
+</div>
+<p>
+ Applets should have About and
+ Manual menu items, typically as the first
+ and second top-most items in the menu respectively. This
+ section describes how the developer creates these menu items
+ and links them to the documentation.
+ </p>
+<p>
+ To add an applet's manual to its applet menu, use:
+<pre class="programlisting">
+/* add an item to the applet menu */
+applet_widget_register_callback(APPLET_WIDGET(applet), "manual",
+_("Manual"), &open_manual, NULL);
+</pre>
+ Here the second argument is an arbitrary name for the
+ callback, the third argument is the label which will appear
+ when the user right clicks on the applet, and the fourth
+ argument is the callback function.
+ </p>
+<p>
+ You will need to write a simple callback function to open the
+ help browser to the appropriate document. This is done using
+ the <tt>gnome_help_file_find_file</tt> function,
+ as described in <a href="indexs08.html" title="Application Help Buttons">the section called “Application Help Buttons”</a>.
+ </p>
+<p>
+ You will also want to add an About menu
+ item to the applet's menu. This is a
+ stock menu item and is done:
+<pre class="programlisting">
+applet_widget_register_stock_callback (APPLET_WIDGET(applet), "about",
+ GNOME_STOCK_MENU_ABOUT, _("About"), &my_applet_cb_about,
+ NULL);
+</pre>
+ </p>
+<p>
+ More information can be found at <a href="http://developer.gnome.org/doc/tutorials/applet/index.html" target="_top">Writing
+ GNOME panel applets using the GTK+/GTK-- widget set</a>.
+ </p>
+</div>
+</div>
+<div class="navfooter">
+<hr>
+<table width="100%" summary="Navigation footer">
+<tr>
+<td width="40%" align="left">
+<a href="indexs08.html">Prev</a> </td>
+<td width="20%" align="center"><a href="index.html">Home</a></td>
+<td width="40%" align="right"> <a href="indexs10.html">Next</a>
+</td>
+</tr>
+<tr>
+<td width="40%" align="left">Application Help Buttons </td>
+<td width="20%" align="center"><a href="index.html">Up</a></td>
+<td width="40%" align="right"> Writing Context Sensitive Help (coming in GNOME-2.0)</td>
+</tr>
+</table>
+</div>
+</body>
+</html>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
+<html>
+<head>
+<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
+<title>Writing Context Sensitive Help (coming in GNOME-2.0)</title>
+<meta name="generator" content="DocBook XSL Stylesheets V1.40">
+<link rel="home" href="index.html" title="The GNOME Handbook of Writing Software Documentation">
+<link rel="up" href="index.html" title="The GNOME Handbook of Writing Software Documentation">
+<link rel="previous" href="indexs09.html" title="Packaging Applet Documentation">
+<link rel="next" href="indexs11.html" title="Referring to Other GNOME Documentation (coming in
+ GNOME-2.0)">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<div class="navheader">
+<table width="100%" summary="Navigation header">
+<tr><th colspan="3" align="center">Writing Context Sensitive Help (coming in GNOME-2.0)</th></tr>
+<tr>
+<td width="20%" align="left">
+<a href="indexs09.html">Prev</a> </td>
+<th width="60%" align="center"> </th>
+<td width="20%" align="right"> <a href="indexs11.html">Next</a>
+</td>
+</tr>
+</table>
+<hr>
+</div>
+<div class="sect1">
+<a name="writingcontextsensitivehelp"></a><div class="titlepage"><div><h2 class="title" style="clear: both">
+<a name="writingcontextsensitivehelp"></a>Writing Context Sensitive Help (coming in GNOME-2.0)</h2></div></div>
+<p>
+ Context sensitive help, also known as "pop-up" help, will allow
+ a user to obtain help information about specific buttons or
+ parts of an application.
+ </p>
+<p>
+ Context sensitive help is still under development and not all
+ the details are available at this time. However, the basics can
+ be shown here so that you can understand how the system will
+ work.
+ </p>
+<p>
+ The Context Sensitive Help system is designed to allow the
+ developer to give an id to a particular portion of the User
+ Interface, for example, a button. Once the interface is complete
+ a Perl script can then be run against the interface code to
+ create a "map" file. This map file allows the developer or
+ writer to associate particular paragraph sections from an XML
+ document to the interface items.
+ </p>
+<p>
+ The XML used for the document is a small XML DTD that is being
+ developed to use the same tags (albeit, much fewer) as DocBook
+ so that writers do not have to re-learn a new DTD.
+ </p>
+<p>
+ Once the document is written and map file is complete, when the
+ user launches context sensitive help on the interface (either by
+ pressing a button and then clicking on the interface item they
+ want information on, or by right mouse clicking on the interface
+ item and selecting a pop-up menu item like "What's This") a
+ small transient window will appear with brief but detailed
+ information on the interface item.
+ </p>
+</div>
+<div class="navfooter">
+<hr>
+<table width="100%" summary="Navigation footer">
+<tr>
+<td width="40%" align="left">
+<a href="indexs09.html">Prev</a> </td>
+<td width="20%" align="center"><a href="index.html">Home</a></td>
+<td width="40%" align="right"> <a href="indexs11.html">Next</a>
+</td>
+</tr>
+<tr>
+<td width="40%" align="left">Packaging Applet Documentation </td>
+<td width="20%" align="center"><a href="index.html">Up</a></td>
+<td width="40%" align="right"> Referring to Other GNOME Documentation (coming in
+ GNOME-2.0)</td>
+</tr>
+</table>
+</div>
+</body>
+</html>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
+<html>
+<head>
+<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
+<title>Referring to Other GNOME Documentation (coming in
+ GNOME-2.0)</title>
+<meta name="generator" content="DocBook XSL Stylesheets V1.40">
+<link rel="home" href="index.html" title="The GNOME Handbook of Writing Software Documentation">
+<link rel="up" href="index.html" title="The GNOME Handbook of Writing Software Documentation">
+<link rel="previous" href="indexs10.html" title="Writing Context Sensitive Help (coming in GNOME-2.0)">
+<link rel="next" href="indexs12.html" title="Basics of Documentation Style">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<div class="navheader">
+<table width="100%" summary="Navigation header">
+<tr><th colspan="3" align="center">Referring to Other GNOME Documentation (coming in
+ GNOME-2.0)</th></tr>
+<tr>
+<td width="20%" align="left">
+<a href="indexs10.html">Prev</a> </td>
+<th width="60%" align="center"> </th>
+<td width="20%" align="right"> <a href="indexs12.html">Next</a>
+</td>
+</tr>
+</table>
+<hr>
+</div>
+<div class="sect1">
+<a name="referring"></a><div class="titlepage"><div><h2 class="title" style="clear: both">
+<a name="referring"></a>Referring to Other GNOME Documentation (coming in
+ GNOME-2.0)</h2></div></div>
+<p>
+ In the GNOME 2.0 Help System, you will be able to create links
+ from one document to another. The exact mechanism for doing
+ this is in development.
+ </p>
+</div>
+<div class="navfooter">
+<hr>
+<table width="100%" summary="Navigation footer">
+<tr>
+<td width="40%" align="left">
+<a href="indexs10.html">Prev</a> </td>
+<td width="20%" align="center"><a href="index.html">Home</a></td>
+<td width="40%" align="right"> <a href="indexs12.html">Next</a>
+</td>
+</tr>
+<tr>
+<td width="40%" align="left">Writing Context Sensitive Help (coming in GNOME-2.0) </td>
+<td width="20%" align="center"><a href="index.html">Up</a></td>
+<td width="40%" align="right"> Basics of Documentation Style</td>
+</tr>
+</table>
+</div>
+</body>
+</html>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
+<html>
+<head>
+<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
+<title>Basics of Documentation Style</title>
+<meta name="generator" content="DocBook XSL Stylesheets V1.40">
+<link rel="home" href="index.html" title="The GNOME Handbook of Writing Software Documentation">
+<link rel="up" href="index.html" title="The GNOME Handbook of Writing Software Documentation">
+<link rel="previous" href="indexs11.html" title="Referring to Other GNOME Documentation (coming in
+ GNOME-2.0)">
+<link rel="next" href="indexs13.html" title="Teamwork">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<div class="navheader">
+<table width="100%" summary="Navigation header">
+<tr><th colspan="3" align="center">Basics of Documentation Style</th></tr>
+<tr>
+<td width="20%" align="left">
+<a href="indexs11.html">Prev</a> </td>
+<th width="60%" align="center"> </th>
+<td width="20%" align="right"> <a href="indexs13.html">Next</a>
+</td>
+</tr>
+</table>
+<hr>
+</div>
+<div class="sect1">
+<a name="basics"></a><div class="titlepage"><div><h2 class="title" style="clear: both">
+<a name="basics"></a>Basics of Documentation Style</h2></div></div>
+<p>
+ Most people have never enjoyed reading a software manual, and
+ they probably never will. Many times, they'll read the
+ documentation only when they run into problems, and they'll be
+ frustrated and upset before they even read a word. On the
+ other hand, some readers will read the manual all the way
+ through, or at least look at the introduction before they
+ start. Your document might serve as a reference for an expert
+ or a guide to a beginner, and it must have enough depth to
+ satisfy the first without overwhelming the second. Ideally, it
+ will serve beginners as they <i>become</i>
+ experts. Remember, your goal is to produce <i>complete,
+ intuitive and clear</i> documentation.
+ </p>
+<p>
+ In order to write useful documentation, you'll have to know who
+ your audience is likely to be. Then, you can look for the
+ problems they're likely to run into, and solve them. It will
+ also help if you focus on the tasks users will perform, and
+ group features accordingly, rather than simply describing
+ features at random.
+ </p>
+<div class="sect2">
+<a name="styleplanning"></a><div class="titlepage"><div><h3 class="title">
+<a name="styleplanning"></a>Planning</h3></div></div>
+<p>
+ Begin documenting by learning how to use the application and
+ reading over any existing documentation. Pay attention to
+ places where your document will differ from the template. It
+ may help to develop a document skeleton: a valid XML or SGML
+ document that has little or no content. For very large
+ applications, you will need to make significant departures
+ from the templates, since you'll be using the
+ <tt><book></tt> tag instead of
+ <tt><chapter></tt> or
+ <tt><article></tt>.
+ </p>
+</div>
+<div class="sect2">
+<a name="balance"></a><div class="titlepage"><div><h3 class="title">
+<a name="balance"></a>Achieving a Balanced Style</h3></div></div>
+<p>
+ Just as you need to juggle expert and novice readers,
+ you'll have to juggle a number of other extremes as you write:
+ <div class="itemizedlist"><ul>
+<li><p>
+<a name="id2909695"></a>
+ Documents should be complete, yet concise. You should
+ describe every feature, but you'll have decide how much
+ detail is really necessary. It's not, for example,
+ necessary to describe every button and form field in a
+ dialog box, but you should make sure that your readers
+ know how to bring up the dialog and what it does. If
+ you spend fewer words on the obvious, you can spend more
+ time clarifying the ambiguous labels and explaining
+ items that are more complex.
+ </p></li>
+<li><p>
+<a name="id2909722"></a>
+ Be engaging and friendly, yet professional. Games
+ documents may be less formal than productivity
+ application documents (people don't
+ <i>use</i> games, they
+ <i>play</i> them), but all of them should
+ maintain a standard of style which holds the reader's
+ interest without resorting to jokes and untranslatable
+ allusions or puns.
+ </p></li>
+<li><p>
+<a name="id2909762"></a>
+ Examples, tips, notes, and screenshots are useful to
+ break up long stretches of text, but too many can get in
+ the way, and make your documents too choppy to read.
+ It's good to provide a screenshot of any dialog windows
+ a user might run into, but if a dialog box has several
+ tabs, it's not usually necessary to have one for each.
+ </p></li>
+<li><p>
+<a name="id2909785"></a>
+ The GDP strives to have all of its documentation conform
+ to certain standards of style and content, but every
+ document (and every writer) is different. You will need
+ to use your judgement, and write documents to fit with
+ the rest of the project, without compromising the
+ individual needs of your subject, or your own
+ individuality as a writer.
+ </p></li>
+</ul></div>
+ </p>
+</div>
+<div class="sect2">
+<a name="stylestructure"></a><div class="titlepage"><div><h3 class="title">
+<a name="stylestructure"></a>Structure</h3></div></div>
+<p>
+ In general, you won't have to worry too much about structure,
+ because the templates provide you with an excellent example.
+ As a general rule, try to follow that structural example.
+ That means using links, hierarchical nesting, and, if
+ necessary, a glossary or index. You probably won't need to
+ use every available structural tag, but take advantage of
+ what DocBook provides you.
+ </p>
+<p>
+ As to linking, there's some disagreement about whether to use
+ <tt><xref></tt> <tt><link></tt>
+ when you make links within your documents. You'll have to
+ decide, based on the different ways that they are presented
+ in output, which is more appropriate given the context.
+ Regardless of which you use, you should not forget to use
+ them. Help your readers find information that relevant to
+ the issue at hand.
+ </p>
+<p>
+ The table of contents will be generated automatically, but
+ you will probably have to develop your own index if you wish
+ to have one. The Nautilus Help Browser will have new, and
+ currently unknown, indexing capabilities, so index style and
+ structure are still under discussion. The GNOME User's Guide
+ will contain a glossary in its next versions; unless you're
+ writing a<tt><book></tt>, it will probably be best to
+ contribute to that rather than developing your own.
+ </p>
+</div>
+<div class="sect2">
+<a name="stylegrammar"></a><div class="titlepage"><div><h3 class="title">
+<a name="stylegrammar"></a>Grammar and Spelling</h3></div></div>
+<p>
+ Nobody expects you to be perfect; they just expect the
+ documentation for their software to be error-free. That means
+ that, in the same way that developers look for bugs and accept
+ bug reports, writers must check for errors in their documents.
+ Poor grammar, bad spelling, and gross technical errors in
+ draft documents are fine. However, if those problems show up
+ in a "real" release, they can count against the credibility of
+ GNOME and Linux. They'll also make you look bad.
+ </p>
+<p>
+ There is no substitute for a human proofreader; use a
+ spell-check program, then read it over yourself, and then find
+ someone else to help you. Other GDP members are, of course,
+ willing and able to help you, but non-writers are often at
+ least as helpful.
+ </p>
+<p>
+ Proofreading documents is both a also a good way to
+ familiarize yourself with documentation, and it certainly
+ makes you valuable to the GDP. Help other writers proof their
+ documents, and they will help you with yours.
+ </p>
+</div>
+</div>
+<div class="navfooter">
+<hr>
+<table width="100%" summary="Navigation footer">
+<tr>
+<td width="40%" align="left">
+<a href="indexs11.html">Prev</a> </td>
+<td width="20%" align="center"><a href="index.html">Home</a></td>
+<td width="40%" align="right"> <a href="indexs13.html">Next</a>
+</td>
+</tr>
+<tr>
+<td width="40%" align="left">Referring to Other GNOME Documentation (coming in
+ GNOME-2.0) </td>
+<td width="20%" align="center"><a href="index.html">Up</a></td>
+<td width="40%" align="right"> Teamwork</td>
+</tr>
+</table>
+</div>
+</body>
+</html>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
+<html>
+<head>
+<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
+<title>Teamwork</title>
+<meta name="generator" content="DocBook XSL Stylesheets V1.40">
+<link rel="home" href="index.html" title="The GNOME Handbook of Writing Software Documentation">
+<link rel="up" href="index.html" title="The GNOME Handbook of Writing Software Documentation">
+<link rel="previous" href="indexs12.html" title="Basics of Documentation Style">
+<link rel="next" href="indexs14.html" title="Finishing A Document">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<div class="navheader">
+<table width="100%" summary="Navigation header">
+<tr><th colspan="3" align="center">Teamwork</th></tr>
+<tr>
+<td width="20%" align="left">
+<a href="indexs12.html">Prev</a> </td>
+<th width="60%" align="center"> </th>
+<td width="20%" align="right"> <a href="indexs14.html">Next</a>
+</td>
+</tr>
+</table>
+<hr>
+</div>
+<div class="sect1">
+<a name="teamwork"></a><div class="titlepage"><div><h2 class="title" style="clear: both">
+<a name="teamwork"></a>Teamwork</h2></div></div>
+<div class="sect2">
+<a name="teamworkgdp"></a><div class="titlepage"><div><h3 class="title">
+<a name="teamworkgdp"></a>Working With The GDP Team</h3></div></div>
+<p>
+ The GDP team is a valuable resource for any documentation
+ author. GDP members can answer most questions documentation
+ authors have during the course of their work. It is also
+ important to make sure you are not duplicating work of other
+ GDP members by visiting the <i>GDP Documentation
+ Status Table</i> (<a href="http://www.gnome.org/gdp/doctable/" target="_top">http://www.gnome.org/gdp/doctable/</a>) and
+ assigning a documentation item to yourself. This table also
+ provides a forum for making suggestions and announcements for
+ each documentation item. The best way to get in touch with
+ GDP members is on the #docs IRC channel at irc.gnome.org or
+ else by emailing the <a href="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/" target="_top">
+ <i>gnome-doc-list mailing list</i></a>.
+ </p>
+<p>
+ After an author has finished a document (or even a draft
+ version of the document), it is a good idea to ask a member of
+ the GDP team to read the document, checking it for grammar,
+ proper DocBook markup, and clarity. One may typically find
+ another author to do this by either asking on the #docs IRC
+ channel at irc.gnome.org or by emailing the <a href="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/" target="_top">
+ <i>gnome-doc-list mailing list</i></a>.
+ </p>
+</div>
+<div class="sect2">
+<a name="teamworkdevelopers"></a><div class="titlepage"><div><h3 class="title">
+<a name="teamworkdevelopers"></a>Working With Developers</h3></div></div>
+<p>
+ Writing documentation typically involves a certain amount of
+ interaction with the developers of GNOME or the application
+ which is being documented. Often a document author will need
+ to ask the developer technical questions during the course of
+ writing a document. After the document is finished, it is good
+ idea to ask the developer to read the document to make sure it
+ is technically correct. The documentation author should also
+ make sure that the application author correctly binds and
+ packages the documentation with the application.
+ </p>
+</div>
+</div>
+<div class="navfooter">
+<hr>
+<table width="100%" summary="Navigation footer">
+<tr>
+<td width="40%" align="left">
+<a href="indexs12.html">Prev</a> </td>
+<td width="20%" align="center"><a href="index.html">Home</a></td>
+<td width="40%" align="right"> <a href="indexs14.html">Next</a>
+</td>
+</tr>
+<tr>
+<td width="40%" align="left">Basics of Documentation Style </td>
+<td width="20%" align="center"><a href="index.html">Up</a></td>
+<td width="40%" align="right"> Finishing A Document</td>
+</tr>
+</table>
+</div>
+</body>
+</html>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
+<html>
+<head>
+<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
+<title>Finishing A Document</title>
+<meta name="generator" content="DocBook XSL Stylesheets V1.40">
+<link rel="home" href="index.html" title="The GNOME Handbook of Writing Software Documentation">
+<link rel="up" href="index.html" title="The GNOME Handbook of Writing Software Documentation">
+<link rel="previous" href="indexs13.html" title="Teamwork">
+<link rel="next" href="indexs15.html" title="Resources">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<div class="navheader">
+<table width="100%" summary="Navigation header">
+<tr><th colspan="3" align="center">Finishing A Document</th></tr>
+<tr>
+<td width="20%" align="left">
+<a href="indexs13.html">Prev</a> </td>
+<th width="60%" align="center"> </th>
+<td width="20%" align="right"> <a href="indexs15.html">Next</a>
+</td>
+</tr>
+</table>
+<hr>
+</div>
+<div class="sect1">
+<a name="finishing"></a><div class="titlepage"><div><h2 class="title" style="clear: both">
+<a name="finishing"></a>Finishing A Document</h2></div></div>
+<div class="sect2">
+<a name="editting"></a><div class="titlepage"><div><h3 class="title">
+<a name="editting"></a>Editing The Document</h3></div></div>
+<p>
+ When the document is finished, the document should be edited
+ by another member of the GDP for spelling, clarity, and
+ DocBook markup. It should also be read by an application
+ author to make sure the document is technically accurate.
+ </p>
+</div>
+<div class="sect2">
+<a name="submitting"></a><div class="titlepage"><div><h3 class="title">
+<a name="submitting"></a>Submitting The Document</h3></div></div>
+<p>
+ After the document has been edited and checked for technical
+ accuracy, it is ready to be combined with the application or
+ documentation package. This is typically done by passing the
+ document to the application or package developer. In some
+ cases, the documents can be committed directly into CVS,
+ however this should only be done after obtaining permission to
+ make CVS commits from the developer. Note that in many cases,
+ the application may need to be modified to correctly link to
+ the documentation. The packaging system (tarballs and binary
+ packages) may also need to be modified to include the
+ documentation in the package. Generally, this should be done
+ by the developers.
+ </p>
+<p>
+ The final step is to email the GNOME Translation Team at
+ <tt><<a href="mailto:gnome-i18n@nuclecu.unam.mx">gnome-i18n@nuclecu.unam.mx</a>></tt> to notify them that
+ there is a new document for them to translate.
+ </p>
+</div>
+</div>
+<div class="navfooter">
+<hr>
+<table width="100%" summary="Navigation footer">
+<tr>
+<td width="40%" align="left">
+<a href="indexs13.html">Prev</a> </td>
+<td width="20%" align="center"><a href="index.html">Home</a></td>
+<td width="40%" align="right"> <a href="indexs15.html">Next</a>
+</td>
+</tr>
+<tr>
+<td width="40%" align="left">Teamwork </td>
+<td width="20%" align="center"><a href="index.html">Up</a></td>
+<td width="40%" align="right"> Resources</td>
+</tr>
+</table>
+</div>
+</body>
+</html>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
+<html>
+<head>
+<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
+<title>Resources</title>
+<meta name="generator" content="DocBook XSL Stylesheets V1.40">
+<link rel="home" href="index.html" title="The GNOME Handbook of Writing Software Documentation">
+<link rel="up" href="index.html" title="The GNOME Handbook of Writing Software Documentation">
+<link rel="previous" href="indexs14.html" title="Finishing A Document">
+<link rel="next" href="apa.html" title="A. Document Templates">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<div class="navheader">
+<table width="100%" summary="Navigation header">
+<tr><th colspan="3" align="center">Resources</th></tr>
+<tr>
+<td width="20%" align="left">
+<a href="indexs14.html">Prev</a> </td>
+<th width="60%" align="center"> </th>
+<td width="20%" align="right"> <a href="apa.html">Next</a>
+</td>
+</tr>
+</table>
+<hr>
+</div>
+<div class="sect1">
+<a name="resources"></a><div class="titlepage"><div><h2 class="title" style="clear: both">
+<a name="resources"></a>Resources</h2></div></div>
+<div class="sect2">
+<a name="resourcesweb"></a><div class="titlepage"><div><h3 class="title">
+<a name="resourcesweb"></a>Resources On The Web</h3></div></div>
+<p> The <a href="http://developer.gnome.org/projects/gdp/" target="_top">GNOME
+ Documentation Project Web page</a> lists current GDP
+ projects and members.
+ </p>
+<p>
+ The <a href="http://www.gnome.org/gdp/doctable/" target="_top">GDP Documentation Status Table</a> tracks the
+ status of all the various documentation components of GNOME.
+ </p>
+<p>
+ Norman Walsh's <a href="http://www.docbook.org" target="_top"> <i>DocBook: The Definitive
+ Guide</i></a> in an excellent book on DocBook,
+ available both online and in print.
+ </p>
+</div>
+<div class="sect2">
+<a name="resourcesbooks"></a><div class="titlepage"><div><h3 class="title">
+<a name="resourcesbooks"></a>Books</h3></div></div>
+<p>
+ Docbook: The Definitive Guide is available in both printed
+ form and on the web at:
+ <a href="http://www.docbook.org/tdg/index.html" target="_top">
+ <i>Docbook: The Definitive Guide</i>
+ </a>
+ </p>
+</div>
+<div class="sect2">
+<a name="mailinglists"></a><div class="titlepage"><div><h3 class="title">
+<a name="mailinglists"></a>Mailing Lists</h3></div></div>
+<p>
+ The <i>gnome-docs-list</i> mailing list is the
+ main discussion area for all contributors to the GNOME
+ Documentation Project. You can find out how to subscribe to
+ this list on <a href="http://www.gnome.org/resources/mailing-lists.html" target="_top">GNOME Mailing Lists</a>. This is a rather
+ low-volume list, so you will not be flooded with messages.
+ </p>
+</div>
+<div class="sect2">
+<a name="irc"></a><div class="titlepage"><div><h3 class="title">
+<a name="irc"></a>IRC</h3></div></div>
+<p>
+ Internet Relay Chat (IRC) is a fast and easy way to get in
+ touch with other GDP members. There are generally at least a
+ few members here who can answer questions or discuss
+ documentation issues. The IRC channel is #docs at
+ irc.gnome.org.
+ </p>
+</div>
+</div>
+<div class="navfooter">
+<hr>
+<table width="100%" summary="Navigation footer">
+<tr>
+<td width="40%" align="left">
+<a href="indexs14.html">Prev</a> </td>
+<td width="20%" align="center"><a href="index.html">Home</a></td>
+<td width="40%" align="right"> <a href="apa.html">Next</a>
+</td>
+</tr>
+<tr>
+<td width="40%" align="left">Finishing A Document </td>
+<td width="20%" align="center"><a href="index.html">Up</a></td>
+<td width="40%" align="right"> A. Document Templates</td>
+</tr>
+</table>
+</div>
+</body>
+</html>
@(cd ../../libxslt ; make xsltproc)
EXTRA_DIST = dict.dtd dict.xml dict.xsl result.xml \
- out/lettera.html out/lettera.orig out/letterb.html out/letterb.orig \
- out/letterc.html out/letterc.orig out/letterd.html out/letterd.orig \
- out/lettere.html out/lettere.orig out/letterf.html out/letterf.orig \
- out/letterg.html out/letterg.orig out/letterh.html out/letterh.orig \
- out/letterij.html out/letterij.orig out/letterk.html out/letterk.orig \
- out/letterl.html out/letterl.orig out/letterm.html out/letterm.orig \
- out/lettern.html out/lettern.orig out/lettero.html out/lettero.orig \
- out/letterp.html out/letterp.orig out/letterq.html out/letterq.orig \
- out/letterr.html out/letterr.orig out/letters.html out/letters.orig \
- out/lettert.html out/lettert.orig out/letteruv.html out/letteruv.orig \
- out/letterw.html out/letterw.orig out/letterx.html out/letterx.orig \
- out/lettery.html out/lettery.orig out/letterz.html out/letterz.orig \
- out/titlepage.html out/titlepage.orig
+ out/lettera.orig out/letterb.orig \
+ out/letterc.orig out/letterd.orig \
+ out/lettere.orig out/letterf.orig \
+ out/letterg.orig out/letterh.orig \
+ out/letterij.orig out/letterk.orig \
+ out/letterl.orig out/letterm.orig \
+ out/lettern.orig out/lettero.orig \
+ out/letterp.orig out/letterq.orig \
+ out/letterr.orig out/letters.orig \
+ out/lettert.orig out/letteruv.orig \
+ out/letterw.orig out/letterx.orig \
+ out/lettery.orig out/letterz.orig \
+ out/titlepage.orig
+
+
+GENERATED = \
+ out/lettera.html out/letterb.html out/letterc.html out/letterd.html \
+ out/lettere.html out/letterf.html out/letterg.html out/letterh.html \
+ out/letterij.html out/letterk.html out/letterl.html out/letterm.html \
+ out/lettern.html out/lettero.html out/letterp.html out/letterq.html \
+ out/letterr.html out/letters.html out/lettert.html out/letteruv.html \
+ out/letterw.html out/letterx.html out/lettery.html out/letterz.html \
+ out/titlepage.html
all: test
@(echo > .memdump)
@($(top_builddir)/libxslt/xsltproc $(srcdir)/dict.xsl $(srcdir)/dict.xml > dict.res ; \
diff $(srcdir)/result.xml dict.res; \
- for i in $(srcdir)/out/letter*.orig ; do \
- diff $$i $(srcdir)/out/`basename $$i .orig`.html; done ; \
- diff $(srcdir)/out/titlepage.orig $(srcdir)/out/titlepage.html; \
+ for i in $(srcdir)/out/letter*.html $(srcdir)/out/titlepage.html ; do \
+ orig=$(srcdir)/out/`basename $$i .html`.orig ; \
+ if [ -f $$orig ] ; then \
+ diff $$orig $$i ; \
+ else \
+ echo "new $$orig" ; cp $$i $$orig ; \
+ fi ; done ; \
grep "MORY ALLO" .memdump | grep -v "MEMORY ALLOCATED : 0" || true;\
- rm -f dict.res)
+ rm -f dict.res $(GENERATED))
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
projects / platform / upstream / libxslt.git / commitdiff